feat: add safe cap call output modes

docs/current_roadmap.md

@@ -43,8 +43,8 @@ clear operator feedback before adding more architecture.
 - Completed: bounded RPC CLI smoke runbook with cleanup commands:
   [`RPC CLI smoke runbook`](runbooks/rpc-cli-smoke.md).
 - Next docs/ergonomics cleanup: make `cap call` output safer for humans without
-  changing default JSON semantics. Active plan:
-  [`cap call output safety`](superpowers/plans/2026-06-09-cap-call-output-safety.md).
+  changing default JSON semantics. Implementation:
+  [`cap call output safety`](historical/superpowers/plans/2026-06-09-cap-call-output-safety.md).
 - Future smoke automation: turn the manual RPC CLI smoke runbook into a small
   script once the command sequence stabilizes.
 - Keep status read-only; do not mutate registry, auth, config, or stores.

docs/runbooks/rpc-cli-smoke.md

@@ -80,6 +80,14 @@ Expected:
 - `outcome` is `ok`.
 - Output is small and machine-readable.
 
+Optionally, test compact output:
+
+```bash
+uv run wf --config wf.config.json cap call wf.std.constant --input '{"value":"smoke"}' --format compact
+```
+
+Expected: one bounded line with `outcome=ok`.
+
 Avoid using arbitrary MCP tools here unless their output shape is known. MCP
 content-block envelopes can be large and should not be treated like compact
 workflow output.

docs/wf_cli.md

@@ -175,6 +175,24 @@ wf cap call wf.std.constant --input '{"value": "hello"}'
 wf --url http://127.0.0.1:8765/rpc cap call everything.default.echo --input '{"message": "hello"}'
 ```
 
+Use `--format compact` for a bounded one-line summary that avoids dumping large
+MCP content-block envelopes:
+
+```bash
+wf cap call wf.std.constant --input '{"value": "hello"}' --format compact
+```
+
+Use `--format text --unwrap-text` to extract exactly one MCP text content block.
+This mode refuses images, resources, blobs, multiple content blocks, and
+non-MCP output:
+
+```bash
+wf cap call everything.default.echo --input '{"message": "hello"}' --format text --unwrap-text
+```
+
+Use `--max-output-chars N` to bound compact/text terminal output. JSON output
+is never truncated.
+
 `cap call` is an authoring/runtime smoke test. It uses the same local or remote
 target selection as the rest of the CLI and returns a normalized outcome,
 output, source id, and diagnostics. Use it to confirm payload shape and upstream

src/wf_cli/commands/caps.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import json
+from enum import StrEnum
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Any
 
 import typer
 
@@ -10,6 +12,13 @@ from wf_cli.formats import ListOutputFormat, emit_list_payload
 from wf_cli.io import CliInputError, emit_json, parse_json_input
 from wf_cli.remote_errors import run_cli_operation
 
+
+class CapCallOutputFormat(StrEnum):
+    JSON = "json"
+    COMPACT = "compact"
+    TEXT = "text"
+
+
 app = typer.Typer(
     name="cap",
     help="Inspect and call workflow capabilities.",
@@ -96,6 +105,25 @@ def call_capability(
             help="Deployment id for saved wrappers with deployment-bound sources.",
         ),
     ] = None,
+    output_format: Annotated[
+        CapCallOutputFormat,
+        typer.Option("--format", help="Output format for rendered cap-call result."),
+    ] = CapCallOutputFormat.JSON,
+    max_output_chars: Annotated[
+        int | None,
+        typer.Option(
+            "--max-output-chars",
+            min=1,
+            help="Maximum characters for compact/text output. JSON output is not truncated.",
+        ),
+    ] = None,
+    unwrap_text: Annotated[
+        bool,
+        typer.Option(
+            "--unwrap-text",
+            help="Only with --format text: unwrap one MCP text block.",
+        ),
+    ] = False,
 ) -> None:
     """Call one workflow capability once for authoring/runtime smoke tests."""
     try:
@@ -112,4 +140,83 @@ def call_capability(
             deployment_id=deployment_id,
         ),
     )
-    emit_json(result)
+    try:
+        rendered = render_cap_call_output(
+            result,
+            output_format=output_format,
+            unwrap_text=unwrap_text,
+            max_output_chars=max_output_chars,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    print(rendered)
+
+
+def render_cap_call_output(
+    result: dict[str, Any],
+    *,
+    output_format: CapCallOutputFormat,
+    unwrap_text: bool,
+    max_output_chars: int | None,
+) -> str:
+    """Render cap-call output without changing the API/RPC payload."""
+    if output_format is CapCallOutputFormat.JSON:
+        return json.dumps(result, indent=2, sort_keys=True)
+    if output_format is CapCallOutputFormat.TEXT:
+        if not unwrap_text:
+            raise ValueError("--format text requires --unwrap-text")
+        return _truncate_text(
+            _unwrap_single_mcp_text_block(result),
+            max_output_chars=max_output_chars,
+        )
+    summary = _compact_cap_call_summary(result)
+    return _truncate_text(summary, max_output_chars=max_output_chars)
+
+
+def _compact_cap_call_summary(result: dict[str, Any]) -> str:
+    output = result.get("output")
+    output_summary = _summarize_output(output)
+    return "\t".join(
+        part
+        for part in (
+            str(result.get("qualified_name", "")),
+            f"source={result.get('source_id')}",
+            f"kind={result.get('kind')}",
+            f"outcome={result.get('outcome')}",
+            f"output={output_summary}",
+        )
+        if part
+    )
+
+
+def _summarize_output(output: object) -> str:
+    if isinstance(output, dict):
+        content = output.get("content")
+        if isinstance(content, list):
+            return f"mcp_content_blocks[{len(content)}]"
+        return f"object keys={sorted(str(key) for key in output.keys())}"
+    if isinstance(output, list):
+        return f"array[{len(output)}]"
+    return type(output).__name__
+
+
+def _unwrap_single_mcp_text_block(result: dict[str, Any]) -> str:
+    output = result.get("output")
+    if not isinstance(output, dict):
+        raise ValueError("--unwrap-text requires exactly one MCP text content block")
+    content = output.get("content")
+    if not isinstance(content, list) or len(content) != 1:
+        raise ValueError("--unwrap-text requires exactly one MCP text content block")
+    block = content[0]
+    if not isinstance(block, dict):
+        raise ValueError("--unwrap-text requires exactly one MCP text content block")
+    if block.get("type") != "text" or not isinstance(block.get("text"), str):
+        raise ValueError("--unwrap-text requires exactly one MCP text content block")
+    return block["text"]
+
+
+def _truncate_text(text: str, *, max_output_chars: int | None) -> str:
+    if max_output_chars is None or len(text) <= max_output_chars:
+        return text
+    remaining = len(text) - max_output_chars
+    return f"{text[:max_output_chars]}...<truncated {remaining} chars>"

tests/wf_cli/test_caps.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import pytest
+from typer.testing import CliRunner
+
+import wf_cli.commands.caps as caps
+from wf_cli.app import app
+from wf_cli.commands.caps import (
+    CapCallOutputFormat,
+    render_cap_call_output,
+)
+from wf_cli.context import CliContext
+
+
+class _FakeHandlers:
+    def __init__(self, result: dict[str, Any]) -> None:
+        self.result = result
+
+    async def call_capability(
+        self,
+        *,
+        qualified_name: str,
+        payload: dict[str, Any],
+        deployment_id: str | None = None,
+    ) -> dict[str, Any]:
+        return self.result
+
+
+def _patch_context(monkeypatch, result: dict[str, Any]) -> None:
+    def _load_context(ctx: object) -> CliContext:
+        from pathlib import Path
+        from typing import cast
+
+        return CliContext(
+            config_path=Path("dummy"),
+            service=None,
+            handlers=_FakeHandlers(result),  # type: ignore[arg-type]
+            source_admin=cast(Any, object()),
+            admin=cast(Any, object()),
+        )
+
+    monkeypatch.setattr(caps, "load_cli_context_from_typer", _load_context)
+
+
+def _base_result(output: object) -> dict[str, object]:
+    return {
+        "qualified_name": "everything.default.echo",
+        "source_id": "everything.default",
+        "kind": "node_spec",
+        "deployment_id": None,
+        "outcome": "ok",
+        "output": output,
+        "diagnostics": [],
+    }
+
+
+def test_render_cap_call_json_is_lossless() -> None:
+    result = _base_result({"value": "hello"})
+
+    rendered = render_cap_call_output(
+        result,
+        output_format=CapCallOutputFormat.JSON,
+        unwrap_text=False,
+        max_output_chars=10,
+    )
+
+    assert json.loads(rendered) == result
+
+
+def test_render_cap_call_compact_summarizes_without_dumping_payload() -> None:
+    result = _base_result({"content": [{"type": "image", "data": "x" * 5000}]})
+
+    rendered = render_cap_call_output(
+        result,
+        output_format=CapCallOutputFormat.COMPACT,
+        unwrap_text=False,
+        max_output_chars=100,
+    )
+
+    assert "everything.default.echo" in rendered
+    assert "outcome=ok" in rendered
+    assert "output=" in rendered
+    assert "x" * 100 not in rendered
+    assert len(rendered) < 200
+
+
+def test_render_cap_call_unwrap_text_for_single_text_block() -> None:
+    result = _base_result(
+        {
+            "content": [
+                {
+                    "type": "text",
+                    "text": "hello from mcp",
+                }
+            ]
+        }
+    )
+
+    rendered = render_cap_call_output(
+        result,
+        output_format=CapCallOutputFormat.TEXT,
+        unwrap_text=True,
+        max_output_chars=100,
+    )
+
+    assert rendered == "hello from mcp"
+
+
+def test_render_cap_call_unwrap_text_rejects_non_text_blocks() -> None:
+    result = _base_result(
+        {
+            "content": [
+                {
+                    "type": "image",
+                    "data": "BASE64",
+                }
+            ]
+        }
+    )
+
+    with pytest.raises(ValueError, match="exactly one MCP text content block"):
+        render_cap_call_output(
+            result,
+            output_format=CapCallOutputFormat.TEXT,
+            unwrap_text=True,
+            max_output_chars=100,
+        )
+
+
+def test_render_cap_call_text_truncates_unwrapped_text() -> None:
+    result = _base_result({"content": [{"type": "text", "text": "abcdef"}]})
+
+    rendered = render_cap_call_output(
+        result,
+        output_format=CapCallOutputFormat.TEXT,
+        unwrap_text=True,
+        max_output_chars=3,
+    )
+
+    assert rendered == "abc...<truncated 3 chars>"
+
+
+def test_cap_call_cli_unwraps_single_mcp_text_block(monkeypatch) -> None:
+    _patch_context(
+        monkeypatch,
+        _base_result({"content": [{"type": "text", "text": "hello text"}]}),
+    )
+
+    result = CliRunner().invoke(
+        app,
+        [
+            "cap",
+            "call",
+            "everything.default.echo",
+            "--input",
+            '{"message": "hello"}',
+            "--format",
+            "text",
+            "--unwrap-text",
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert result.output.strip() == "hello text"
+
+
+def test_cap_call_cli_refuses_to_unwrap_blob_content(monkeypatch) -> None:
+    _patch_context(
+        monkeypatch,
+        _base_result({"content": [{"type": "image", "data": "BASE64"}]}),
+    )
+
+    result = CliRunner().invoke(
+        app,
+        [
+            "cap",
+            "call",
+            "everything.default.image",
+            "--input",
+            "{}",
+            "--format",
+            "text",
+            "--unwrap-text",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert "exactly one MCP text content block" in result.output
+
+
+def test_cap_call_cli_refuses_to_unwrap_multiple_text_blocks(monkeypatch) -> None:
+    _patch_context(
+        monkeypatch,
+        _base_result(
+            {"content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}]}
+        ),
+    )
+
+    result = CliRunner().invoke(
+        app,
+        [
+            "cap",
+            "call",
+            "everything.default.echo",
+            "--input",
+            "{}",
+            "--format",
+            "text",
+            "--unwrap-text",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert "exactly one MCP text content block" in result.output

tests/wf_cli/test_remote_target.py

@@ -358,6 +358,32 @@ def test_wf_cap_commands_use_rpc_url_override(monkeypatch, tmp_path) -> None:
     assert called_payload["outcome"] == "ok"
     assert called_payload["output"] == {"value": "hello cap call"}
 
+    compact = runner.invoke(
+        app,
+        [
+            "--config",
+            str(config_path),
+            "--url",
+            "http://test/rpc",
+            "cap",
+            "call",
+            "wf.std.constant",
+            "--input",
+            '{"value": "hello cap call"}',
+            "--format",
+            "compact",
+        ],
+    )
+    assert compact.exit_code == 0, compact.output
+    assert "wf.std.constant" in compact.output
+    assert "outcome=ok" in compact.output
+    assert "hello cap call" not in compact.output
+
+    help_result = runner.invoke(app, ["cap", "call", "--help"])
+    assert help_result.exit_code == 0
+    assert "--unwrap-text" in help_result.output
+    assert "MCP text block" in help_result.output
+
 
 def test_wf_source_commands_use_rpc_url_override(monkeypatch, tmp_path) -> None:
     server = build_local_static_workflow_server(tmp_path / "store")