honcho-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/CHANGELOG.md

@@ -5,7 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [Unreleased]
+## [0.5.0] - 2026-11-05
+
+### Added
+
+- `honcho dream list` and `honcho dream inspect <id>` (Representation History): list the dreams in a workspace, newest first, or the dreams about one peer with `-p`, and see what a dream changed. `inspect` shows the conclusions it created, each with the conclusions it was derived from and where those stand now (current, removed and by which dream, or unavailable once deleted or removed longer ago than history is kept); the conclusions it removed, as they read when removed; and the peer card before and after. A dream past the retention window shows when it was pruned and keeps only the conclusions it created that still exist. Needs a workspace or admin key, and Honcho v3.6.0+ (#1542)
+
+### Changed
+
+- Requires `honcho-ai` 2.9.0 or newer, the first Python SDK with `dreams()` and `get_dream()`
+
+### Fixed
+
+- `HONCHO_API_KEY` wins over a saved OAuth grant, as the documented flag > env > file order says. Before, `HONCHO_API_KEY=<key> honcho workspace list` quietly ran as the saved OAuth identity. A run with an env key no longer refreshes or writes `~/.honcho/config.json`, and an OAuth refresh under `HONCHO_API_KEY` or `HONCHO_BASE_URL` no longer writes those values into it, which had switched every other tool sharing the file to that key's org. A refreshed grant records the host it was refreshed against, and `honcho doctor` names the env key as the credential in use (#1518)
+
+## [0.4.0] - 2026-10-29
+
+### Added
+
+- `source_message_ids` on conclusion output: the messages an explicit conclusion cites as evidence (Honcho v3.5.0+; a count in table mode, the full list in JSON). `conclusion list --cites <message_id>` narrows to the conclusions that cite a message. Null in JSON on servers or SDKs that predate the field (#935)
+
+### Changed
+
+- Requires `honcho-ai` 2.8.0 or newer, the first Python SDK that carries `source_message_ids`
 
 ## [0.3.0] - 2026-10-23
 
@@ -24,6 +46,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - `honcho session summaries`, `honcho session inspect`, `honcho session context` and `honcho workspace queue-status` emit nested SDK objects (summaries, context messages, per-session queue status) as JSON objects instead of Python repr strings like `"content='...' message_id='...'"` (#1324)
 
+## [0.2.1] - 2026-10-20
+
+### Fixed
+
+- `honcho session summaries`, `honcho session inspect`, `honcho session context` and `honcho workspace queue-status` emit nested SDK objects (summaries, context messages, per-session queue status) as JSON objects instead of Python repr strings like `"content='...' message_id='...'"` (#1324)
+
 ## [0.2.0] - 2026-09-21
 
 ### Added

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: honcho-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: A terminal for Honcho — memory that reasons.
 Project-URL: Homepage, https://github.com/plastic-labs/honcho
 Project-URL: Repository, https://github.com/plastic-labs/honcho
@@ -15,7 +15,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Requires-Dist: certifi>=2026.10.19
 Requires-Dist: click>=8.0.0
-Requires-Dist: honcho-ai>=2.5.0
+Requires-Dist: honcho-ai>=2.9.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: questionary>=2.1.0
 Requires-Dist: rich>=13.0.0
@@ -166,6 +166,13 @@ honcho stop --wipe     # also delete volumes
 | `honcho conclusion create` | Create a conclusion |
 | `honcho conclusion delete <id>` | Delete a conclusion |
 
+### Dreams (Representation History)
+
+| Command | Description |
+|---------|-------------|
+| `honcho dream list` | Dreams in the workspace, newest first (`-p` for dreams about one peer, `--observer` for one representation) |
+| `honcho dream inspect <id>` | What one dream changed: conclusions created (with what each was derived from), conclusions removed, and the peer card before and after |
+
 ### Config
 
 | Command | Description |

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/README.md

@@ -139,6 +139,13 @@ honcho stop --wipe     # also delete volumes
 | `honcho conclusion create` | Create a conclusion |
 | `honcho conclusion delete <id>` | Delete a conclusion |
 
+### Dreams (Representation History)
+
+| Command | Description |
+|---------|-------------|
+| `honcho dream list` | Dreams in the workspace, newest first (`-p` for dreams about one peer, `--observer` for one representation) |
+| `honcho dream inspect <id>` | What one dream changed: conclusions created (with what each was derived from), conclusions removed, and the peer card before and after |
+
 ### Config
 
 | Command | Description |

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "honcho-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "A terminal for Honcho — memory that reasons."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -19,7 +19,7 @@ classifiers = [
 dependencies = [
     "click>=8.0.0",
     "typer>=0.15.0",
-    "honcho-ai>=2.5.0",
+    "honcho-ai>=2.9.0",
     "rich>=13.0.0",
     "httpx>=0.27.0",
     "questionary>=2.1.0",

honcho_cli-0.5.0/src/honcho_cli/__init__.py

@@ -0,0 +1,11 @@
+"""Honcho CLI — a terminal for Honcho."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # pyproject.toml is the single source of the version; reading it from the
+    # installed metadata keeps --version, the update check and the
+    # X-Honcho-Host header in step with each release bump.
+    __version__ = version("honcho-cli")
+except PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0+unknown"

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/src/honcho_cli/_help.py

@@ -91,6 +91,7 @@ def print_welcome(console: Console) -> None:
         ("",           "remove-session · status"),
         ("message",    "list · create · get"),
         ("conclusion", "list · create · search · delete"),
+        ("dream",      "list · inspect"),
         ("config",     "inspect current configuration"),
     ]
     memory_rows = [
@@ -103,6 +104,7 @@ def print_welcome(console: Console) -> None:
         ("honcho peer chat \"...\" -p <peer> --scope <scope>", "answer from one scope's sessions only"),
         ("honcho peer card -p <peer> -w <workspace>", "synthesized identity: traits, preferences, instructions"),
         ("honcho conclusion list -p <peer> -w <workspace>", "browse peer conclusions"),
+        ("honcho dream list -p <peer> -w <workspace>", "dreams about a peer; inspect one to see what it changed"),
         ("honcho session view / context -s <session>", "transcript, or what an agent would see"),
         ("honcho workspace queue-status", "is the deriver processing?"),
     ]

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/src/honcho_cli/commands/conclusion.py

@@ -21,23 +21,29 @@ add_common_options(app)
 _LEVELS = ("explicit", "deductive", "inductive", "contradiction")
 
 #: Columns carrying a conclusion's attribution, shown alongside the content.
-_ATTRIBUTION_COLUMNS = ["id", "level", "source_ids", "times_derived", "content"]
+_ATTRIBUTION_COLUMNS = ["id", "level", "source_ids", "source_message_ids", "times_derived", "content"]
 
 
 def _format_conclusion(c, workspace_id: str | None) -> dict:
     """Shape a Conclusion for output.
 
     ``level``, ``source_ids`` and ``times_derived`` are the attribution the
-    server started returning in Honcho v3.2.0. In table mode ``source_ids``
-    collapses to a count, since the ids are nanoids and a list of them makes
-    the row unreadable; JSON mode keeps the full list so it can be piped back
-    into ``honcho conclusion get``.
+    server started returning in Honcho v3.2.0; ``source_message_ids`` (the
+    messages an explicit conclusion cites) arrived in v3.5.0 and is read
+    leniently so older SDKs still work. In table mode the id lists collapse
+    to counts, since nanoids make the row unreadable; JSON mode keeps them so
+    they can be piped back into ``honcho conclusion get`` or ``message get``.
     """
     source_ids = c.source_ids or []
+    # JSON keeps None ("no citation record") apart from [] ("cites nothing").
+    source_message_ids = getattr(c, "source_message_ids", None)
     return {
         "id": c.id,
         "level": c.level,
         "source_ids": source_ids if use_json() else len(source_ids),
+        "source_message_ids": source_message_ids
+        if use_json()
+        else len(source_message_ids or []),
         "times_derived": c.times_derived,
         "content": c.content if use_json() else c.content[:160],
         "workspace_id": workspace_id,
@@ -86,6 +92,11 @@ def list_conclusions(
         "--derived-from",
         help="Only conclusions derived from this conclusion ID",
     ),
+    cites: Optional[str] = typer.Option(
+        None,
+        "--cites",
+        help="Only explicit conclusions that cite this message ID as evidence",
+    ),
     workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
     peer: Optional[str] = typer.Option(None, "--peer", "-p", help="Override peer ID"),
     json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
@@ -104,6 +115,8 @@ def list_conclusions(
         filters["level"] = level
     if derived_from:
         filters["source_ids"] = {"contains": derived_from}
+    if cites:
+        filters["source_message_ids"] = {"contains": cites}
 
     try:
         if observed:

honcho_cli-0.5.0/src/honcho_cli/commands/dream.py

@@ -0,0 +1,318 @@
+"""Dream commands: list, inspect.
+
+Representation History: every dream records what it changed in a peer's
+representation — the conclusions it created (with the conclusions each was
+derived from), the conclusions it removed (with their text as it read when
+removed), and the peer card before and after. Runs are kept for the server's
+retention window (30 days by default). Needs a workspace or admin key.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+import typer
+from rich.console import Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from honcho_cli._help import HonchoTyperGroup
+from honcho_cli.commands.workspace import _handle_error
+from honcho_cli.common import add_common_options, get_client, handle_cmd_flags
+from honcho_cli.output import (
+    _format_timestamp,
+    print_error,
+    print_json,
+    status,
+    stdout_console,
+    use_json,
+)
+from honcho_cli.validation import validate_resource_id
+
+app = typer.Typer(
+    cls=HonchoTyperGroup,
+    help="List dreams and inspect what each one changed in a peer's representation.",
+)
+add_common_options(app)
+
+
+_STATUS_STYLE = {
+    "completed": "green",
+    "running": "cyan",
+    "failed": "red",
+    "interrupted": "yellow",
+}
+
+def _short_time(value: datetime | None) -> str:
+    """``YYYY-MM-DD HH:MM`` UTC — a dream takes minutes, not milliseconds."""
+    return _format_timestamp(value)[:16].replace("T", " ") if value else ""
+
+
+def _changes(run: Any) -> Text:
+    text = Text()
+    text.append(f"+{run.created_count}", style="green" if run.created_count else "dim")
+    text.append(" ")
+    text.append(f"-{run.removed_count}", style="red" if run.removed_count else "dim")
+    if run.peer_card_updated:
+        text.append("  card", style="cyan")
+    return text
+
+
+def _print_runs(runs: list, title: str) -> None:
+    """Dream runs as a table. Run IDs never truncate: they feed `dream inspect`."""
+    table = Table(title=title, show_header=True, header_style="bold")
+    # min_width holds the id whole in a narrow terminal; the rest wrap instead.
+    table.add_column("id", no_wrap=True, min_width=max(len(run.id) for run in runs))
+    table.add_column("started (UTC)", style="dim")
+    table.add_column("status")
+    table.add_column("observer → observed", overflow="fold")
+    table.add_column("type", style="dim", overflow="fold")
+    table.add_column("changes")
+    for run in runs:
+        table.add_row(
+            run.id,
+            _short_time(run.started_at),
+            Text(run.status, style=_STATUS_STYLE.get(run.status, "")),
+            f"{run.observer_id} → {run.observed_id}",
+            " · ".join(part for part in (run.dream_type, run.trigger_reason) if part),
+            _changes(run),
+        )
+    stdout_console.print(table)
+
+
+@app.command("list")
+def list_dreams(
+    observer: Optional[str] = typer.Option(
+        None,
+        "--observer",
+        help="Only dreams from this observer's perspective (with -p: one representation)",
+    ),
+    limit: int = typer.Option(20, "--limit", help="Dreams per page"),
+    page: int = typer.Option(1, "--page", help="Page number, newest dreams first"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    peer: Optional[str] = typer.Option(
+        None, "--peer", "-p", help="Only dreams about this peer (the observed peer)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """List dreams in the workspace, newest first.
+
+    Pass -p to see the dreams about one peer, and --observer to narrow to one
+    observer's model of that peer. `honcho dream inspect <id>` shows what a
+    dream changed.
+    """
+    handle_cmd_flags(json_output=json_output, workspace=workspace, peer=peer)
+    if limit < 1 or page < 1:
+        print_error("INVALID_ARGUMENT", "--limit and --page must be positive")
+        raise typer.Exit(1)
+    if observer:
+        validate_resource_id(observer, "peer")
+    client, config = get_client()
+
+    try:
+        # An unset peer is "" in config; "" would filter to no peer at all.
+        result = client.dreams(
+            observed=config.peer_id or None, observer=observer or None, page=page, size=limit
+        )
+        if use_json():
+            print_json([run.model_dump(mode="json") for run in result.items])
+            return
+        title = "Dreams"
+        if config.peer_id:
+            title += f" about {config.peer_id}"
+        if result.pages:
+            title += f" · page {result.page}/{result.pages}"
+        if not result.items:
+            status("No dreams recorded in the retention window.")
+            return
+        _print_runs(result.items, title)
+        if result.pages and page < result.pages:
+            status(f"more: --page {page + 1}")
+    except Exception as e:
+        _handle_error(e, "dream", "list")
+
+
+def _duration(started: datetime, finished: datetime | None) -> str:
+    if finished is None:
+        return ""
+    seconds = int((finished - started).total_seconds())
+    minutes, seconds = divmod(seconds, 60)
+    return f"{minutes}m {seconds:02d}s" if minutes else f"{seconds}s"
+
+
+def _removed_note(removed_in_run: str | None, run_id: str) -> str:
+    if removed_in_run == run_id:
+        return "removed in this dream"
+    return f"removed by dream {removed_in_run}" if removed_in_run else "removed"
+
+
+def _source_line(source: Any, run_id: str) -> Text:
+    """One source conclusion, marked by what has happened to it since."""
+    line = Text("  ")
+    if source.status == "current":
+        line.append("● ", style="green")
+        line.append(source.content or "")
+    elif source.status == "removed":
+        line.append("✕ ", style="red")
+        line.append(source.content or "", style="strike dim")
+        line.append(f"  {_removed_note(source.removed_in_run, run_id)}", style="dim red")
+    else:
+        line.append("? ", style="dim")
+        line.append(
+            f"{source.id} (unavailable: deleted, or removed longer ago than history is kept)",
+            style="dim",
+        )
+    return line
+
+
+def _header(detail: Any) -> Panel:
+    status_text = Text(detail.status, style=f"bold {_STATUS_STYLE.get(detail.status, '')}")
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="bold")
+    grid.add_column()
+    grid.add_row("representation", f"{detail.observer_id} → {detail.observed_id}")
+    grid.add_row(
+        "type",
+        " · ".join(part for part in (detail.dream_type, detail.trigger_reason) if part),
+    )
+    grid.add_row("status", status_text)
+    grid.add_row("started", _format_timestamp(detail.started_at))
+    if detail.finished_at:
+        grid.add_row(
+            "finished",
+            f"{_format_timestamp(detail.finished_at)}  "
+            f"({_duration(detail.started_at, detail.finished_at)})",
+        )
+    if detail.pruned_at:
+        grid.add_row(
+            "pruned",
+            Text(
+                f"{_format_timestamp(detail.pruned_at)}  past retention: only "
+                "created conclusions that still exist are shown",
+                style="dim",
+            ),
+        )
+    grid.add_row(
+        "changes",
+        Text.assemble(
+            (f"+{detail.created_count} created", "green"),
+            "  ",
+            (f"-{detail.removed_count} removed", "red"),
+            "  ",
+            ("peer card updated" if detail.peer_card_updated else "peer card unchanged", "dim"),
+        ),
+    )
+    return Panel(grid, title=f"dream {detail.id}", title_align="left")
+
+
+def _created_table(detail: Any) -> Table:
+    table = Table(
+        title=f"Created ({len(detail.created)})",
+        title_justify="left",
+        show_header=True,
+        header_style="bold",
+        show_lines=True,
+        expand=True,
+    )
+    table.add_column("specialist", style="dim", no_wrap=True)
+    table.add_column("level", no_wrap=True)
+    table.add_column("conclusion, and what it was derived from", ratio=1)
+    for created in detail.created:
+        conclusion = created.conclusion
+        body = Text()
+        body.append("+ ", style="bold green")
+        if conclusion.status == "current":
+            body.append(conclusion.content or "")
+        elif conclusion.status == "removed":
+            body.append(conclusion.content or "", style="strike")
+            body.append(
+                f"  ({_removed_note(conclusion.removed_in_run, detail.id)})", style="dim red"
+            )
+        else:
+            body.append(f"{conclusion.id} (unavailable)", style="dim")
+        lines = [body] + [_source_line(source, detail.id) for source in created.sources]
+        table.add_row(created.specialist or "", conclusion.level or "", Group(*lines))
+    return table
+
+
+def _removed_table(detail: Any) -> Table:
+    replacements = {c.conclusion.id: c.conclusion.content for c in detail.created}
+    table = Table(
+        title=f"Removed ({len(detail.removed)})",
+        title_justify="left",
+        show_header=True,
+        header_style="bold",
+        show_lines=True,
+        expand=True,
+    )
+    table.add_column("specialist", style="dim", no_wrap=True)
+    table.add_column("level", no_wrap=True)
+    table.add_column("conclusion, as it read when removed", ratio=1)
+    for removed in detail.removed:
+        body = Text()
+        body.append("- ", style="bold red")
+        body.append(removed.content)
+        lines = [body]
+        if removed.replaced_by:
+            replacement = replacements.get(removed.replaced_by) or removed.replaced_by
+            lines.append(Text(f"  replaced by: {replacement}", style="dim"))
+        table.add_row(removed.specialist or "", removed.level or "", Group(*lines))
+    return table
+
+
+def _peer_card_panel(detail: Any) -> Panel:
+    before = list(detail.peer_card.before or [])
+    after = list(detail.peer_card.after)
+    lines: list[Text] = []
+    for entry in before:
+        if entry not in after:
+            lines.append(Text(f"- {entry}", style="red"))
+    for entry in after:
+        if entry in before:
+            lines.append(Text(f"  {entry}", style="dim"))
+        else:
+            lines.append(Text(f"+ {entry}", style="green"))
+    if not lines:
+        lines.append(Text("(empty)", style="dim"))
+    return Panel(Group(*lines), title="Peer card", title_align="left")
+
+
+@app.command()
+def inspect(
+    run_id: str = typer.Argument(help="Dream run ID, from `honcho dream list`"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """Show what one dream changed.
+
+    Lists the conclusions it created, each with the conclusions it was derived
+    from; the conclusions it removed, as they read when removed; and the peer
+    card before and after. Each source shows where it stands now: current,
+    removed (and by which dream), or unavailable once deleted or removed longer
+    ago than history is kept.
+    """
+    handle_cmd_flags(json_output=json_output, workspace=workspace)
+    validate_resource_id(run_id, "dream")
+    client, _config = get_client()
+
+    try:
+        detail = client.get_dream(run_id)
+    except Exception as e:
+        _handle_error(e, "dream", run_id)
+        return
+
+    if use_json():
+        print_json(detail.model_dump(mode="json"))
+        return
+
+    stdout_console.print(_header(detail))
+    if detail.created:
+        stdout_console.print(_created_table(detail))
+    if detail.removed:
+        stdout_console.print(_removed_table(detail))
+    if detail.peer_card is not None:
+        stdout_console.print(_peer_card_panel(detail))
+    if not (detail.created or detail.removed or detail.peer_card):
+        status("This dream committed no changes.")

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/src/honcho_cli/commands/setup.py

@@ -334,6 +334,8 @@ def _check_connection(base_url: str, api_key: str) -> None:
 
 def _auth_mode_detail(config: CLIConfig) -> str:
     """Human summary of which credential the CLI will use."""
+    if config.api_key_from_env:
+        return "API key (HONCHO_API_KEY)"
     tokens = config.usable_oauth()
     if tokens is not None:
         if tokens.access_valid():

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/src/honcho_cli/common.py

@@ -64,10 +64,13 @@ def get_flag_overrides() -> dict[str, str | None]:
 def maybe_refresh_token(config: CLIConfig) -> None:
     """Refresh an expired OAuth access token in place and persist it.
 
-    No-op when there is no grant for the current host or the token is still
-    valid. A dead grant degrades to the saved apiKey with a warning; exits
-    only when nothing is left to authenticate with.
+    No-op when HONCHO_API_KEY is set (the env key wins, so the grant goes
+    unused), when there is no grant for the current host, or when the token is
+    still valid. A dead grant degrades to the saved apiKey with a warning;
+    exits only when nothing is left to authenticate with.
     """
+    if config.api_key_from_env:
+        return
     tokens = config.usable_oauth()
     if tokens is None or tokens.access_valid():
         return
@@ -83,15 +86,19 @@ def maybe_refresh_token(config: CLIConfig) -> None:
         if refreshed is not None:
             # rotation-safe: persist the (possibly new) refresh token before
             # it's reused; keep the old one if the server didn't rotate
-            # (refresh_token is optional)
+            # (refresh_token is optional). Only the grant is written: config
+            # carries env overrides that must not land in the shared file.
+            # Bind it to the host it was refreshed against, so a legacy
+            # hostless grant refreshed under HONCHO_BASE_URL isn't later sent
+            # to the saved environmentUrl.
             config.oauth = OAuthTokens.from_response(
                 refreshed,
                 client_id=tokens.client_id,
                 scope_fallback=tokens.scope,
                 refresh_fallback=tokens.refresh_token,
-                host=tokens.host,
+                host=config.base_url,
             )
-            config.save()
+            config.save(oauth_only=True)
             return
 
     if config.api_key:

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/src/honcho_cli/config.py

@@ -12,7 +12,8 @@ The CLI owns these top-level keys in that file:
 
 ``apiKey`` (manual admin JWT) is shared with sibling tools: the CLI writes it
 on paste-key login and reads it as a fallback, but never deletes it. A live
-OAuth token takes precedence over ``apiKey`` for the CLI's own calls.
+OAuth token takes precedence over ``apiKey`` for the CLI's own calls, and
+``HONCHO_API_KEY`` takes precedence over both.
 
 All other top-level keys (``hosts``, ``sessions``, ``saveMessages``,
 ``sessionStrategy``, …) are written by sibling Honcho tools and are
@@ -148,6 +149,7 @@ class CLIConfig:
     peer_id: str = ""
     session_id: str = ""
     oauth: OAuthTokens | None = None
+    api_key_from_env: bool = False  # api_key came from HONCHO_API_KEY, not the file
 
     def usable_oauth(self) -> OAuthTokens | None:
         """The OAuth grant, if present and bound to the current host."""
@@ -160,12 +162,15 @@ class CLIConfig:
         return None
 
     def resolved_api_key(self) -> str:
-        """The key handed to the SDK: a live OAuth token wins, else apiKey.
+        """The key handed to the SDK: HONCHO_API_KEY, else a live OAuth token, else apiKey.
 
-        An expired grant loses to a saved apiKey (a dead grant degrades to the
-        shared key) but still wins over nothing, since the server is the final
-        judge.
+        An env key is an explicit per-run choice, so it beats the stored grant
+        (flag > env > file). An expired grant loses to a saved apiKey (a dead
+        grant degrades to the shared key) but still wins over nothing, since
+        the server is the final judge.
         """
+        if self.api_key_from_env:
+            return self.api_key
         tokens = self.usable_oauth()
         if tokens and tokens.access_valid():
             return tokens.access_token
@@ -214,16 +219,22 @@ class CLIConfig:
                 # strings with a Pydantic ValidationError. Drop them so the
                 # SDK falls back to kwargs / defaults.
                 os.environ.pop(env_var, None)
+        config.api_key_from_env = bool(os.environ.get(ENV_MAP["api_key"]))
 
         return config
 
-    def save(self) -> None:
+    def save(self, *, oauth_only: bool = False) -> None:
         """Write ``environmentUrl`` + credentials to config.json.
 
         Preserves unrelated top-level keys (``hosts``, ``sessions``,
         ``saveMessages``, ``sessionStrategy``, …) that other tools write.
         ``apiKey`` is written when set but never removed — sibling tools read
         it. The ``oauth`` block is CLI-owned and dropped when empty.
+
+        ``oauth_only`` writes just the ``oauth`` block. A config from
+        ``load()`` carries env overrides (``HONCHO_API_KEY``,
+        ``HONCHO_BASE_URL``), and a token refresh must not copy them into the
+        shared file, where sibling tools would pick them up.
         """
         CONFIG_DIR.mkdir(parents=True, exist_ok=True)
 
@@ -237,9 +248,10 @@ class CLIConfig:
             except (json.JSONDecodeError, OSError):
                 data = {}
 
-        data["environmentUrl"] = self.base_url
-        if self.api_key:
-            data["apiKey"] = self.api_key
+        if not oauth_only:
+            data["environmentUrl"] = self.base_url
+            if self.api_key:
+                data["apiKey"] = self.api_key
 
         if self.oauth and self.oauth.access_token:
             data["oauth"] = {
@@ -269,7 +281,7 @@ class CLIConfig:
         result: dict[str, str] = {}
         for fld in fields(self):
             val = getattr(self, fld.name)
-            if not val:
+            if not val or fld.name == "api_key_from_env":
                 continue
             if fld.name == "api_key":
                 # Show ``***<last4>`` only — enough to compare keys without

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/src/honcho_cli/main.py

@@ -87,6 +87,7 @@ def help_cmd(ctx: typer.Context) -> None:
 # Register command groups
 from honcho_cli.commands.config_cmd import app as config_app
 from honcho_cli.commands.conclusion import app as conclusion_app
+from honcho_cli.commands.dream import app as dream_app
 from honcho_cli.commands.message import app as message_app
 from honcho_cli.commands.peer import app as peer_app
 from honcho_cli.commands.scope import app as scope_app
@@ -98,6 +99,7 @@ app.add_typer(session_app,    name="session")
 app.add_typer(scope_app,      name="scope")
 app.add_typer(message_app,    name="message")
 app.add_typer(conclusion_app, name="conclusion")
+app.add_typer(dream_app,      name="dream")
 app.add_typer(workspace_app,  name="workspace")
 app.add_typer(config_app,     name="config")
 

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/tests/test_common.py

@@ -5,13 +5,15 @@ from __future__ import annotations
 import json
 import os
 import time
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 import typer
 from honcho_cli import common
 from honcho_cli.config import CLIConfig, OAuthTokens
+from honcho_cli.main import app
 from honcho_cli.oauth import OAuthFlowError, TokenResponse
+from typer.testing import CliRunner
 
 
 @pytest.fixture
@@ -95,6 +97,84 @@ def test_expired_token_refreshes_and_persists(cfg_path):
     assert on_disk["refreshToken"] == "new-rt"
 
 
+def test_refresh_does_not_persist_env_overrides(cfg_path, monkeypatch):
+    """A refresh writes the new grant only, never the HONCHO_BASE_URL overlay.
+
+    Sibling tools read ``environmentUrl`` and ``apiKey`` from the shared file,
+    so a leaked override silently moves them to another server or org. (With
+    HONCHO_API_KEY set the refresh is skipped altogether.) A legacy grant with
+    no recorded host is trusted on any URL, so it refreshes under the override.
+    """
+    original = {
+        "apiKey": "file-key",
+        "environmentUrl": "http://localhost:8000",
+        "oauth": {
+            "accessToken": "old-at",
+            "refreshToken": "old-rt",
+            "accessExpiresAt": time.time() - 100,
+            "clientId": "honcho-cli",
+            "scope": "write",
+        },
+        "hosts": {"harness": {"workspace": "harness-honcho"}},
+    }
+    cfg_path.write_text(json.dumps(original))
+    monkeypatch.setenv("HONCHO_BASE_URL", "http://127.0.0.1:9000")
+    rotated = TokenResponse(
+        access_token="new-at", refresh_token="new-rt", expires_in=3600, scope="write"
+    )
+    client = MagicMock()
+    client.workspaces.return_value = ["ws-a"]
+    with (
+        patch("honcho_cli.oauth.refresh_access_token", return_value=rotated),
+        patch("honcho_cli.common.Honcho", return_value=client),
+    ):
+        result = CliRunner().invoke(app, ["workspace", "list"])
+    assert result.exit_code == 0, result.output
+
+    on_disk = json.loads(cfg_path.read_text())
+    assert on_disk["apiKey"] == "file-key"
+    assert on_disk["environmentUrl"] == "http://localhost:8000"
+    assert on_disk["hosts"] == original["hosts"]
+    assert on_disk["oauth"]["accessToken"] == "new-at"
+    assert on_disk["oauth"]["refreshToken"] == "new-rt"
+    # bound to the override it was minted against, not left hostless for the saved URL
+    assert on_disk["oauth"]["host"] == "http://127.0.0.1:9000"
+
+
+def test_env_api_key_beats_live_oauth_grant(cfg_path, monkeypatch):
+    """HONCHO_API_KEY is an explicit per-run choice, so it outranks the saved grant."""
+    cfg_path.write_text(json.dumps({
+        "environmentUrl": "http://localhost:8000",
+        "oauth": {
+            "accessToken": "oauth-at",
+            "refreshToken": "oauth-rt",
+            "accessExpiresAt": time.time() + 3600,
+            "host": "http://localhost:8000",
+        },
+    }))
+    monkeypatch.setenv("HONCHO_API_KEY", "other-org-key")
+    client = MagicMock()
+    client.workspaces.return_value = ["ws-a"]
+    with patch("honcho_cli.common.Honcho", return_value=client) as honcho:
+        result = CliRunner().invoke(app, ["workspace", "list"])
+    assert result.exit_code == 0, result.output
+    assert honcho.call_args.kwargs["api_key"] == "other-org-key"
+
+
+def test_env_api_key_skips_refresh(cfg_path, monkeypatch):
+    """The env key wins, so an expired grant it won't use is neither refreshed nor saved."""
+    cfg_path.write_text(json.dumps(
+        {"oauth": {"accessToken": "old-at", "refreshToken": "old-rt", "accessExpiresAt": 0}}
+    ))
+    before = cfg_path.read_text()
+    monkeypatch.setenv("HONCHO_API_KEY", "other-org-key")
+    config = CLIConfig.load()
+    with patch("honcho_cli.oauth.refresh_access_token") as refresh:
+        common.maybe_refresh_token(config)
+    refresh.assert_not_called()
+    assert cfg_path.read_text() == before
+
+
 def test_refresh_failure_exits(cfg_path):
     config = _cfg(time.time() - 100)
     with patch("honcho_cli.oauth.refresh_access_token", side_effect=OAuthFlowError("invalid_grant")):

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/tests/test_conclusion_attribution.py

@@ -32,12 +32,18 @@ def runner():
     return CliRunner()
 
 
-def _conclusion(cid: str, level: str = "inductive", source_ids: list[str] | None = None) -> MagicMock:
+def _conclusion(
+    cid: str,
+    level: str = "inductive",
+    source_ids: list[str] | None = None,
+    source_message_ids: list[str] | None = None,
+) -> MagicMock:
     return MagicMock(
         id=cid,
         content=f"content for {cid}",
         level=level,
         source_ids=source_ids if source_ids is not None else ["p1", "p2"],
+        source_message_ids=source_message_ids,
         times_derived=3,
         observer_id="alice",
         observed_id="alice",
@@ -59,10 +65,42 @@ class TestConclusionAttribution:
         row = json.loads(result.stdout)[0]
         assert row["level"] == "inductive"
         assert row["source_ids"] == ["p1", "p2"]
+        assert row["source_message_ids"] is None
         assert row["times_derived"] == 3
         # --level reaches the server as a filter rather than being applied locally
         assert client.peer.return_value.conclusions.list.call_args.kwargs["filters"] == {"level": "inductive"}
 
+    def test_list_reports_cited_messages_and_filters_by_them(self, cfg, runner):
+        client = MagicMock()
+        config = MagicMock(workspace_id="ws1", peer_id="alice")
+        client.peer.return_value.conclusions.list.return_value = MagicMock(
+            items=[_conclusion("c1", level="explicit", source_ids=[], source_message_ids=["m1", "m2"])]
+        )
+
+        with patch("honcho_cli.commands.conclusion.get_client", return_value=(client, config)):
+            result = runner.invoke(app, ["conclusion", "list", "--cites", "m1", "-p", "alice"])
+
+        assert result.exit_code == 0
+        row = json.loads(result.stdout)[0]
+        assert row["source_message_ids"] == ["m1", "m2"]
+        assert client.peer.return_value.conclusions.list.call_args.kwargs["filters"] == {
+            "source_message_ids": {"contains": "m1"}
+        }
+
+    def test_list_tolerates_sdks_without_source_message_ids(self, cfg, runner):
+        """An SDK predating the field must not break the listing."""
+        client = MagicMock()
+        config = MagicMock(workspace_id="ws1", peer_id="alice")
+        legacy = _conclusion("c1", level="explicit", source_ids=[])
+        del legacy.source_message_ids
+        client.peer.return_value.conclusions.list.return_value = MagicMock(items=[legacy])
+
+        with patch("honcho_cli.commands.conclusion.get_client", return_value=(client, config)):
+            result = runner.invoke(app, ["conclusion", "list", "-p", "alice"])
+
+        assert result.exit_code == 0
+        assert json.loads(result.stdout)[0]["source_message_ids"] is None
+
     def test_list_rejects_an_unknown_level(self, cfg, runner):
         result = runner.invoke(app, ["conclusion", "list", "--level", "nonsense", "-p", "alice"])
         assert result.exit_code == 1

honcho_cli-0.5.0/tests/test_dream.py

@@ -0,0 +1,234 @@
+"""`honcho dream list` / `honcho dream inspect` (Representation History)."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from unittest.mock import MagicMock, patch
+
+import pytest
+from honcho import NotFoundError
+from honcho.api_types import DreamRunDetailResponse, DreamRunResponse
+from typer.testing import CliRunner
+
+from honcho_cli.main import app
+
+STARTED = datetime(2026, 11, 3, 12, 0, tzinfo=timezone.utc)
+FINISHED = datetime(2026, 11, 3, 12, 1, 30, tzinfo=timezone.utc)
+
+
+@pytest.fixture
+def cfg(tmp_path, monkeypatch):
+    f = tmp_path / "config.json"
+    monkeypatch.setattr("honcho_cli.config.CONFIG_DIR", tmp_path)
+    monkeypatch.setattr("honcho_cli.config.CONFIG_FILE", f)
+    for k in [k for k in os.environ if k.startswith("HONCHO_")]:
+        monkeypatch.delenv(k)
+    f.write_text(json.dumps({"apiKey": "k", "environmentUrl": "http://localhost:8000"}))
+    return f
+
+
+@pytest.fixture
+def runner():
+    return CliRunner()
+
+
+def _run(**overrides) -> DreamRunResponse:
+    fields = {
+        "id": "run1",
+        "observer_id": "maya",
+        "observed_id": "maya",
+        "dream_type": "omni",
+        "trigger_reason": "threshold",
+        "status": "completed",
+        "created_count": 1,
+        "removed_count": 1,
+        "peer_card_updated": True,
+        "started_at": STARTED,
+        "finished_at": FINISHED,
+    }
+    fields.update(overrides)
+    return DreamRunResponse(**fields)
+
+
+def _detail() -> DreamRunDetailResponse:
+    return DreamRunDetailResponse(
+        **_run().model_dump(),
+        created=[
+            {
+                "conclusion": {
+                    "id": "c3",
+                    "content": "Maya relies on caffeine to get through night shifts",
+                    "level": "deductive",
+                    "status": "current",
+                },
+                "sources": [
+                    {
+                        "id": "c1",
+                        "content": "Maya drinks coffee daily",
+                        "level": "explicit",
+                        "status": "removed",
+                        "removed_in_run": "run1",
+                    },
+                    {
+                        "id": "c2",
+                        "content": "Maya works night shifts",
+                        "level": "explicit",
+                        "status": "current",
+                    },
+                    {"id": "c0", "status": "unavailable"},
+                ],
+                "specialist": "deduction",
+            }
+        ],
+        removed=[
+            {
+                "id": "c1",
+                "content": "Maya drinks coffee daily",
+                "level": "explicit",
+                "replaced_by": "c3",
+                "specialist": "deduction",
+            }
+        ],
+        peer_card={
+            "before": ["IDENTITY: Name: Maya", "ATTRIBUTE: Drinks coffee"],
+            "after": ["IDENTITY: Name: Maya", "ATTRIBUTE: Works night shifts"],
+        },
+    )
+
+
+def _client_with(**methods) -> MagicMock:
+    client = MagicMock()
+    for name, value in methods.items():
+        setattr(client, name, value)
+    return client
+
+
+def test_list_filters_by_peer_and_observer(cfg, runner):
+    page = MagicMock(items=[_run()], page=1, pages=1)
+    dreams = MagicMock(return_value=page)
+    config = MagicMock(peer_id="maya", workspace_id="ws1")
+    with patch(
+        "honcho_cli.commands.dream.get_client",
+        return_value=(_client_with(dreams=dreams), config),
+    ):
+        result = runner.invoke(
+            app,
+            ["dream", "list", "-w", "ws1", "-p", "maya", "--observer", "assistant", "--limit", "5"],
+        )
+
+    assert result.exit_code == 0, result.stderr
+    dreams.assert_called_once_with(observed="maya", observer="assistant", page=1, size=5)
+    [row] = json.loads(result.stdout)
+    assert (row["id"], row["status"], row["created_count"]) == ("run1", "completed", 1)
+
+
+def test_list_without_a_peer_sends_no_peer_filter(cfg, runner):
+    dreams = MagicMock(return_value=MagicMock(items=[], page=1, pages=0))
+    config = MagicMock(peer_id="", workspace_id="ws1")  # the config default
+    with patch(
+        "honcho_cli.commands.dream.get_client",
+        return_value=(_client_with(dreams=dreams), config),
+    ):
+        result = runner.invoke(app, ["dream", "list", "-w", "ws1"])
+
+    assert result.exit_code == 0, result.stderr
+    dreams.assert_called_once_with(observed=None, observer=None, page=1, size=20)
+    assert json.loads(result.stdout) == []
+
+
+def test_list_rejects_non_positive_paging(cfg, runner):
+    result = runner.invoke(app, ["dream", "list", "-w", "ws1", "--limit", "0"])
+    assert result.exit_code == 1
+    assert json.loads(result.stderr)["error"]["code"] == "INVALID_ARGUMENT"
+
+
+def test_list_renders_full_run_ids_for_a_terminal(cfg, runner):
+    run_id = "kRkwKbgz4bqSRJjRXmp2_"
+    page = MagicMock(items=[_run(id=run_id, removed_count=0)], page=1, pages=1)
+    config = MagicMock(peer_id="maya", workspace_id="ws1")
+    with (
+        patch(
+            "honcho_cli.commands.dream.get_client",
+            return_value=(_client_with(dreams=MagicMock(return_value=page)), config),
+        ),
+        patch("honcho_cli.commands.dream.use_json", return_value=False),
+    ):
+        narrow = runner.invoke(app, ["dream", "list", "-w", "ws1", "-p", "maya"], env={"COLUMNS": "60"})
+        wide = runner.invoke(app, ["dream", "list", "-w", "ws1", "-p", "maya"], env={"COLUMNS": "160"})
+
+    assert narrow.exit_code == 0, narrow.stderr
+    assert run_id in narrow.stdout  # the other columns wrap; the id never does
+    assert "maya → maya" in wide.stdout
+    assert "+1 -0  card" in wide.stdout
+
+
+def test_inspect_json_is_the_full_detail(cfg, runner):
+    get_dream = MagicMock(return_value=_detail())
+    with patch(
+        "honcho_cli.commands.dream.get_client",
+        return_value=(_client_with(get_dream=get_dream), MagicMock()),
+    ):
+        result = runner.invoke(app, ["dream", "inspect", "run1", "-w", "ws1"])
+
+    assert result.exit_code == 0, result.stderr
+    get_dream.assert_called_once_with("run1")
+    body = json.loads(result.stdout)
+    assert body["created"][0]["sources"][0]["status"] == "removed"
+    assert body["removed"][0]["replaced_by"] == "c3"
+    assert body["peer_card"]["after"][1] == "ATTRIBUTE: Works night shifts"
+
+
+def test_inspect_renders_changes_for_a_terminal(cfg, runner):
+    get_dream = MagicMock(return_value=_detail())
+    with (
+        patch(
+            "honcho_cli.commands.dream.get_client",
+            return_value=(_client_with(get_dream=get_dream), MagicMock()),
+        ),
+        patch("honcho_cli.commands.dream.use_json", return_value=False),
+    ):
+        result = runner.invoke(app, ["dream", "inspect", "run1", "-w", "ws1"])
+
+    assert result.exit_code == 0, result.stderr
+    out = result.stdout
+    assert "maya → maya" in out
+    assert "1m 30s" in out
+    assert "Maya relies on caffeine" in out
+    assert "removed in this dream" in out
+    assert "unavailable" in out
+    assert "replaced by: Maya relies on caffeine" in out
+    assert "- ATTRIBUTE: Drinks coffee" in out
+    assert "+ ATTRIBUTE: Works night shifts" in out
+
+
+def test_inspect_says_when_retention_pruned_the_run(cfg, runner):
+    detail = _detail().model_copy(
+        update={"pruned_at": FINISHED, "removed": [], "peer_card": None}
+    )
+    get_dream = MagicMock(return_value=detail)
+    with (
+        patch(
+            "honcho_cli.commands.dream.get_client",
+            return_value=(_client_with(get_dream=get_dream), MagicMock()),
+        ),
+        patch("honcho_cli.commands.dream.use_json", return_value=False),
+    ):
+        result = runner.invoke(app, ["dream", "inspect", "run1", "-w", "ws1"])
+
+    assert result.exit_code == 0, result.stderr
+    assert "past retention" in result.stdout
+    assert "Maya relies on caffeine" in result.stdout
+
+
+def test_inspect_unknown_dream_exits_with_not_found(cfg, runner):
+    get_dream = MagicMock(side_effect=NotFoundError("not found"))
+    with patch(
+        "honcho_cli.commands.dream.get_client",
+        return_value=(_client_with(get_dream=get_dream), MagicMock()),
+    ):
+        result = runner.invoke(app, ["dream", "inspect", "nope", "-w", "ws1"])
+
+    assert result.exit_code == 1
+    assert json.loads(result.stderr)["error"]["code"] == "DREAM_NOT_FOUND"

honcho_cli-0.5.0/tests/test_version.py

@@ -0,0 +1,13 @@
+"""The CLI's reported version must match the version it is published under."""
+
+import tomllib
+from pathlib import Path
+
+from honcho_cli import __version__
+
+
+def test_version_matches_pyproject():
+    pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+    expected = tomllib.loads(pyproject.read_text())["project"]["version"]
+
+    assert __version__ == expected

{honcho_cli-0.3.0 → honcho_cli-0.5.0}/uv.lock

@@ -74,21 +74,21 @@ wheels = [
 
 [[package]]
 name = "honcho-ai"
-version = "2.0.1"
+version = "2.6.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "httpx" },
     { name = "pydantic" },
     { name = "typing-extensions", marker = "python_full_version < '3.12'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/93/30/d30ba159404050d53b4b1b1c4477f9591f43af18758be1fb7dab6afbfe7d/honcho_ai-2.0.1.tar.gz", hash = "sha256:6fdeebf9454e62bc523d57888e50359e67baafdb21f68621f9c14e08dc00623a", size = 46732, upload-time = "2026-02-09T21:03:26.99Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/26/a7/13ad4c1b66d1a96ac66ce8cbb6e7d4d4f91cd0c4380b00caca8d27e273eb/honcho_ai-2.6.0.tar.gz", hash = "sha256:a799eb9fd3f02e34fb2a4166d8262ed407e02d276ad446e68affb370be45e47c", size = 68183, upload-time = "2026-10-14T16:30:28.525Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e2/de/83fda0c057cfa11d6b5ed532623184591aa7dcff4a067934ba6811026229/honcho_ai-2.0.1-py3-none-any.whl", hash = "sha256:94887e61d59f353e1e1e20b395858040780f5d67ca1e9d450538646544e4e42f", size = 56780, upload-time = "2026-02-09T21:03:25.992Z" },
+    { url = "https://files.pythonhosted.org/packages/16/a5/e95f89a29b519e9e0293281b7fd8b6333c72ce44be8707cca4e452ac224e/honcho_ai-2.6.0-py3-none-any.whl", hash = "sha256:819cdd5775ecae69f617b14d60c3ea3c6ac9404b3821fa50cbf0b681aa2283cf", size = 79216, upload-time = "2026-10-14T16:30:27.211Z" },
 ]
 
 [[package]]
 name = "honcho-cli"
-version = "0.1.1"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -107,7 +107,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
-    { name = "honcho-ai", specifier = ">=0.1.0" },
+    { name = "honcho-ai", specifier = ">=2.5.0" },
     { name = "httpx", specifier = ">=0.27.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0.0" },
     { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.14.0" },

honcho_cli-0.3.0/src/honcho_cli/__init__.py

@@ -1,3 +0,0 @@
-"""Honcho CLI — a terminal for Honcho."""
-
-__version__ = "0.3.0"