mash-cli 0.1.0__tar.gz

mash_cli-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: mash-cli
+Version: 0.1.0
+Summary: Interactive CLI shell package for Mash applications
+Author: imsid
+License: Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mashpy>=0.1.2
+Requires-Dist: prompt_toolkit>=3.0.36
+Requires-Dist: rich>=13.7.1
+
+# mash-cli
+
+Interactive CLI package for Mash applications.
+
+It provides:
+
+- `mash` console command
+- `mash_cli.CLIAppShell` and related command primitives for app shells
+
+Install options:
+
+- `pip install mash-cli`
+- `pip install "mashpy[cli]"`

mash_cli-0.1.0/README.md

@@ -0,0 +1,13 @@
+# mash-cli
+
+Interactive CLI package for Mash applications.
+
+It provides:
+
+- `mash` console command
+- `mash_cli.CLIAppShell` and related command primitives for app shells
+
+Install options:
+
+- `pip install mash-cli`
+- `pip install "mashpy[cli]"`

mash_cli-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "mash-cli"
+version = "0.1.0"
+description = "Interactive CLI shell package for Mash applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Proprietary"}
+authors = [{ name = "imsid" }]
+dependencies = [
+  "mashpy>=0.1.2",
+  "prompt_toolkit>=3.0.36",
+  "rich>=13.7.1",
+]
+
+[project.scripts]
+mash = "mash_cli.main:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mash_cli*"]

mash_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mash_cli-0.1.0/src/mash_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Mash CLI shell package."""
+
+from .commands import Command, CommandRegistry
+from .shell import CLIAppShell, SubagentRegistration
+from .types import CLIContext
+
+__all__ = ["CLIAppShell", "SubagentRegistration", "CLIContext", "Command", "CommandRegistry"]

mash_cli-0.1.0/src/mash_cli/chain_renderer.py

@@ -0,0 +1,316 @@
+"""Real-time chain of thought renderer for agent execution."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from rich.console import Console
+from rich.live import Live
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from mash.logging.events import AgentTraceEvent, LLMEvent
+
+
+class ChainOfThoughtRenderer:
+    """Renders agent's chain of thought in real-time."""
+
+    def __init__(self, console: Optional[Console] = None) -> None:
+        """Initialize renderer.
+
+        Args:
+            console: Rich console instance. Creates new one if not provided.
+        """
+        self._console = console or Console()
+        self._current_trace_id: Optional[str] = None
+        self._current_step: int = 0
+        self._steps: List[Dict[str, Any]] = []
+        self._live: Optional[Live] = None
+        self._enabled = True
+
+    def enable(self) -> None:
+        """Enable rendering."""
+        self._enabled = True
+
+    def disable(self) -> None:
+        """Disable rendering."""
+        self._enabled = False
+
+    def start_trace(self, trace_id: Optional[str]) -> None:
+        """Start a new execution trace.
+
+        Args:
+            trace_id: Unique trace identifier.
+        """
+        if not self._enabled:
+            return
+        if not trace_id:
+            return
+        self._current_trace_id = trace_id
+        self._current_step = 0
+        self._steps = []
+        self._console.print("\n[bold cyan]Agent Execution Started[/bold cyan]")
+
+    def on_think_complete(self, event: AgentTraceEvent) -> None:
+        """Handle think complete event.
+
+        Args:
+            event: Agent trace event.
+        """
+        if not self._enabled:
+            return
+
+        # Start new trace if needed
+        if event.trace_id != self._current_trace_id:
+            self.start_trace(event.trace_id)
+
+        # Extract tool_calls_detail from payload if available
+        tool_calls_detail = None
+        assistant_text = None
+        if hasattr(event, "payload") and event.payload:
+            tool_calls_detail = event.payload.get("tool_calls_detail")
+            assistant_text = event.payload.get("assistant_text")
+
+        step_info = {
+            "step": event.step_id,
+            "action_type": event.action_type,
+            "tool_calls": event.tool_calls,
+            "tool_calls_detail": tool_calls_detail,
+            "assistant_text": assistant_text,
+            "token_usage": event.token_usage,
+            "think_duration": event.duration_ms,
+        }
+        self._steps.append(step_info)
+
+        # Render thinking
+        self._render_think(step_info)
+
+    def on_act_complete(self, event: AgentTraceEvent) -> None:
+        """Handle act complete event.
+
+        Args:
+            event: Agent trace event.
+        """
+        if not self._enabled or not self._steps:
+            return
+
+        # Update last step with act duration
+        self._steps[-1]["act_duration"] = event.duration_ms
+        self._render_act(self._steps[-1])
+
+    def on_step_complete(self, event: AgentTraceEvent) -> None:
+        """Handle step complete event.
+
+        Args:
+            event: Agent trace event.
+        """
+        if not self._enabled or not self._steps:
+            return
+
+        # Update last step with total duration
+        self._steps[-1]["total_duration"] = event.duration_ms
+        self._render_step_complete(self._steps[-1])
+        self._current_step += 1
+
+    def on_llm_request_start(self) -> None:
+        """Handle LLM request start."""
+        if not self._enabled:
+            return
+        # Could show a spinner here if desired
+
+    def on_llm_request_complete(self, event: LLMEvent) -> None:
+        """Handle LLM request complete.
+
+        Args:
+            event: LLM event.
+        """
+        # Events are already captured in think_complete via token_usage
+
+    def finish_trace(self) -> None:
+        """Finish the current trace."""
+        if not self._enabled:
+            return
+        if self._steps:
+            self._render_summary()
+        self._current_trace_id = None
+        self._steps = []
+
+    def _render_think(self, step: Dict[str, Any]) -> None:
+        """Render thinking phase.
+
+        Args:
+            step: Step information.
+        """
+        action_type = step.get("action_type", "unknown")
+        tool_calls = step.get("tool_calls") or []
+        tool_calls_detail = step.get("tool_calls_detail") or []
+        assistant_text = step.get("assistant_text")
+        token_usage = step.get("token_usage") or {}
+        think_duration = step.get("think_duration", 0)
+
+        # Build step description
+        if action_type == "tool_call" and tool_calls:
+            tools_str = ", ".join(f"[yellow]{t}[/yellow]" for t in tool_calls)
+            desc = f"Calling tools: {tools_str}"
+        elif action_type == "response":
+            desc = "[green]Generating response[/green]"
+        elif action_type == "finish":
+            desc = "[blue]Finishing execution[/blue]"
+        else:
+            desc = f"Action: {action_type}"
+
+        # Show tokens if available
+        token_str = ""
+        if token_usage:
+            input_tok = token_usage.get("input", 0)
+            output_tok = token_usage.get("output", 0)
+            token_str = f" [dim]({input_tok}+{output_tok} tokens)[/dim]"
+
+        self._console.print(
+            f"  [cyan]→[/cyan] Step {self._current_step + 1}: {desc}{token_str} "
+            f"[dim]{think_duration}ms[/dim]"
+        )
+
+        if assistant_text:
+            self._console.print(f"    [dim]assistant: {assistant_text}[/dim]")
+
+        # Show tool commands/arguments if available
+        if tool_calls_detail:
+            for tool_call in tool_calls_detail:
+                tool_name = tool_call.get("name", "unknown")
+                tool_args = tool_call.get("arguments", {})
+
+                # Special handling for bash tool to show the command
+                if tool_name == "bash" and "command" in tool_args:
+                    command = tool_args["command"]
+                    # Truncate long commands
+                    if len(command) > 80:
+                        command = command[:77] + "..."
+                    self._console.print(f"    [dim]$ {command}[/dim]")
+                # For other tools, show arguments more generically
+                elif tool_args:
+                    # Show first few keys/values
+                    args_preview = []
+                    for key, value in list(tool_args.items())[:2]:
+                        if isinstance(value, str) and len(value) > 40:
+                            value = value[:37] + "..."
+                        args_preview.append(f"{key}={value}")
+                    if len(tool_args) > 2:
+                        args_preview.append(f"+{len(tool_args) - 2} more")
+                    args_str = ", ".join(args_preview)
+                    self._console.print(f"    [dim]{tool_name}({args_str})[/dim]")
+
+    def _render_act(self, step: Dict[str, Any]) -> None:
+        """Render action phase.
+
+        Args:
+            step: Step information.
+        """
+        act_duration = step.get("act_duration", 0)
+        tool_calls = step.get("tool_calls") or []
+
+        if tool_calls:
+            self._console.print(
+                f"    [dim]✓ Executed {len(tool_calls)} tool(s) in {act_duration}ms[/dim]"
+            )
+
+    def _render_step_complete(self, step: Dict[str, Any]) -> None:
+        """Render step completion.
+
+        Args:
+            step: Step information.
+        """
+        # Just a blank line for spacing
+        # self._console.print()
+
+    def _render_summary(self) -> None:
+        """Render execution summary."""
+        if not self._steps:
+            return
+
+        total_steps = len(self._steps)
+        total_duration = sum(s.get("total_duration", 0) for s in self._steps)
+        total_tokens = sum(
+            s.get("token_usage", {}).get("input", 0)
+            + s.get("token_usage", {}).get("output", 0)
+            for s in self._steps
+        )
+
+        # Count tool calls
+        tool_calls = []
+        for step in self._steps:
+            if step.get("tool_calls"):
+                tool_calls.extend(step["tool_calls"])
+
+        summary = Text()
+        summary.append("\nAgent Execution Complete: ", style="bold green")
+        summary.append(f"{total_steps} steps, ", style="dim")
+        summary.append(f"{len(tool_calls)} tools, ", style="dim")
+        summary.append(f"{total_tokens:,} tokens, ", style="dim")
+        summary.append(f"{total_duration:,}ms", style="dim")
+
+        self._console.print(summary)
+
+
+class CompactChainRenderer:
+    """Compact single-line renderer for agent execution."""
+
+    def __init__(self, console: Optional[Console] = None) -> None:
+        """Initialize compact renderer.
+
+        Args:
+            console: Rich console instance.
+        """
+        self._console = console or Console()
+        self._enabled = True
+        self._current_step = 0
+
+    def enable(self) -> None:
+        """Enable rendering."""
+        self._enabled = True
+
+    def disable(self) -> None:
+        """Disable rendering."""
+        self._enabled = False
+
+    def start_trace(self, trace_id: Optional[str]) -> None:
+        """Start trace."""
+        if not self._enabled:
+            return
+        if not trace_id:
+            return
+        self._current_step = 0
+        self._console.print("[dim]Thinking...[/dim]", end=" ")
+
+    def on_think_complete(self, event: AgentTraceEvent) -> None:
+        """Handle think complete."""
+        if not self._enabled:
+            return
+
+        action_type = event.action_type
+        tool_calls = event.tool_calls or []
+
+        if action_type == "tool_call" and tool_calls:
+            # Show tool icons
+            for _ in tool_calls:
+                self._console.print("[yellow]⚡[/yellow]", end="")
+        elif action_type == "response":
+            self._console.print("[green]💬[/green]", end="")
+        elif action_type == "finish":
+            self._console.print("[blue]✓[/blue]", end="")
+
+    def on_act_complete(self) -> None:
+        """Handle act complete."""
+        # Compact mode doesn't show act separately
+
+    def on_step_complete(self) -> None:
+        """Handle step complete."""
+        if not self._enabled:
+            return
+        self._current_step += 1
+
+    def finish_trace(self) -> None:
+        """Finish trace."""
+        if not self._enabled:
+            return
+        self._console.print()  # New line after all steps

mash_cli-0.1.0/src/mash_cli/commands.py

@@ -0,0 +1,198 @@
+"""Command system for CLI applications."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, Protocol
+
+from mash.logging.events import CommandEvent
+
+if TYPE_CHECKING:
+    from .types import CLIContext
+
+CommandHandler = Callable[["CLIContext", List[str]], None]
+
+
+class SupportsCommandEventLogger(Protocol):
+    """Minimal command-event logger interface."""
+
+    def emit(self, event: CommandEvent) -> None:
+        """Emit one command event."""
+
+
+@dataclass(frozen=True)
+class Command:
+    """Command definition."""
+
+    name: str
+    help: str
+    handler: CommandHandler
+    aliases: tuple[str, ...] = ()
+
+
+class CommandRegistry:
+    """Registry for managing commands."""
+
+    def __init__(
+        self,
+        app_id: str,
+        event_logger: Optional[SupportsCommandEventLogger],
+        session_id: str,
+    ) -> None:
+        """Initialize command registry.
+
+        Args:
+            event_logger: Eevent logger for logging command execution.
+            session_id: session ID for event logging.
+            app_id: app ID for event logging.
+        """
+        self._commands: Dict[str, Command] = {}
+        self._lookup: Dict[str, Command] = {}
+        self._event_logger = event_logger
+        self._session_id = session_id
+        self._app_id = app_id
+
+    def register(self, command: Command) -> None:
+        """Register a command.
+
+        Args:
+            command: Command to register.
+
+        Raises:
+            ValueError: If command name is empty or already registered.
+        """
+        name = self._normalize(command.name)
+        if not name:
+            raise ValueError("Command name cannot be empty")
+
+        if name in self._commands:
+            raise ValueError(f"Command '{name}' is already registered")
+
+        self._commands[name] = command
+        self._lookup[name] = command
+
+        # Register aliases
+        for alias in command.aliases:
+            alias_key = self._normalize(alias)
+            if alias_key:
+                self._lookup[alias_key] = command
+
+    def unregister(self, name: str) -> None:
+        """Unregister a command.
+
+        Args:
+            name: Command name to unregister.
+        """
+        name = self._normalize(name)
+        self._commands.pop(name, None)
+        # Remove from lookup
+        to_remove = [k for k, v in self._lookup.items() if v.name == name]
+        for k in to_remove:
+            self._lookup.pop(k, None)
+
+    def get(self, name: str) -> Command | None:
+        """Get a command by name or alias.
+
+        Args:
+            name: Command name or alias.
+
+        Returns:
+            Command if found, None otherwise.
+        """
+        return self._lookup.get(self._normalize(name))
+
+    def list_commands(self) -> List[Command]:
+        """List all registered commands.
+
+        Returns:
+            List of commands sorted by name.
+        """
+        return sorted(self._commands.values(), key=lambda c: c.name)
+
+    def execute(self, ctx: CLIContext, line: str) -> bool:
+        """Execute a command if the line is a command.
+
+        Args:
+            ctx: CLI context.
+            line: Input line.
+
+        Returns:
+            True if line was a command, False otherwise.
+        """
+        line = line.strip()
+        if not line or not line.startswith("/"):
+            return False
+
+        # Parse command
+        payload = line[1:].strip()
+        if not payload:
+            ctx.renderer.warn("Unknown command. Try /help.")
+            return True
+
+        parts = payload.split()
+        cmd_name = parts[0]
+        args = parts[1:]
+
+        # Find command
+        command = self.get(cmd_name)
+        if not command:
+            ctx.renderer.warn(f"Unknown command: /{cmd_name}. Try /help.")
+            return True
+
+        # Execute command with logging
+        start_time = time.time()
+        command_name = f"/{command.name}"
+        args_str = " ".join(args)
+
+        # Log command start
+        if self._event_logger:
+
+            self._event_logger.emit(
+                CommandEvent(
+                    event_type="command.start",
+                    app_id=self._app_id,
+                    session_id=self._session_id,
+                    command_name=command_name,
+                    args=args_str,
+                )
+            )
+
+        try:
+            command.handler(ctx, args)
+
+            # Log command completion
+            if self._event_logger:
+
+                self._event_logger.emit(
+                    CommandEvent(
+                        event_type="command.complete",
+                        app_id=self._app_id,
+                        session_id=self._session_id,
+                        command_name=command_name,
+                        duration_ms=int((time.time() - start_time) * 1000),
+                    )
+                )
+        except Exception as e:
+            ctx.renderer.error(f"Command failed: {str(e)}")
+
+            # Log command error
+            if self._event_logger:
+
+                self._event_logger.emit(
+                    CommandEvent(
+                        event_type="command.error",
+                        app_id=self._app_id,
+                        session_id=self._session_id,
+                        command_name=command_name,
+                        error=str(e),
+                        duration_ms=int((time.time() - start_time) * 1000),
+                    )
+                )
+
+        return True
+
+    @staticmethod
+    def _normalize(name: str) -> str:
+        """Normalize command name."""
+        return name.lower().strip()

mash_cli-0.1.0/src/mash_cli/default_commands.py

@@ -0,0 +1,193 @@
+"""Default slash commands for CLI shells."""
+
+from __future__ import annotations
+
+import json
+from .commands import Command
+
+
+def register_default_commands(shell) -> None:
+    """Register built-in commands for a CLI shell."""
+
+    def help_command(ctx, _args: list[str]) -> None:
+        commands = shell.command_registry.list_commands()
+        if not commands:
+            ctx.renderer.info("No commands available.")
+            return
+
+        ctx.renderer.info("Available commands:")
+        for command in commands:
+            aliases = f" (aliases: {', '.join(command.aliases)})" if command.aliases else ""
+            ctx.renderer.print(f"  /{command.name}{aliases} - {command.help}")
+
+    def exit_command(_ctx, _args: list[str]) -> None:
+        raise SystemExit(0)
+
+    def clear_command(ctx, _args: list[str]) -> None:
+        ctx.renderer.clear()
+
+    def session_command(ctx, _args: list[str]) -> None:
+        runtime = ctx.runtime
+        ctx.renderer.info(f"App: {ctx.app_id}")
+        ctx.renderer.info(f"Session ID: {ctx.session_id}")
+        ctx.renderer.info(f"Primary agent: {runtime.app_id}")
+        subagent_ids = runtime.get_subagent_ids()
+        if subagent_ids:
+            ctx.renderer.info(f"Subagents: {', '.join(subagent_ids)}")
+        ctx.renderer.info(f"Model: {runtime.get_model()}")
+        ctx.renderer.info(f"Max steps: {runtime.get_max_steps()}")
+        ctx.renderer.info(
+            f"Session tokens: {runtime.get_session_total_tokens(ctx.session_id)}"
+        )
+
+    def prefs_command(ctx, args: list[str]) -> None:
+        runtime = ctx.runtime
+        if not args:
+            prefs = runtime.get_latest_preferences()
+            if prefs:
+                ctx.renderer.info("Current preferences:")
+                ctx.renderer.print(json.dumps(prefs, indent=2))
+            else:
+                ctx.renderer.warn("No preferences set.")
+            return
+
+        subcommand = args[0].lower()
+        if subcommand == "set":
+            if len(args) < 2:
+                ctx.renderer.error("Usage: /prefs set <json>")
+                return
+            try:
+                prefs = json.loads(" ".join(args[1:]))
+                if not isinstance(prefs, dict):
+                    ctx.renderer.error("Preferences must be a JSON object")
+                    return
+                runtime.set_preferences(ctx.session_id, prefs)
+                ctx.renderer.info("Preferences saved successfully.")
+            except json.JSONDecodeError as exc:
+                ctx.renderer.error(f"Invalid JSON: {exc}")
+            return
+
+        if subcommand == "clear":
+            runtime.set_preferences(ctx.session_id, {})
+            ctx.renderer.info("Preferences cleared.")
+            return
+
+        ctx.renderer.error(f"Unknown subcommand: {subcommand}")
+        ctx.renderer.info("Usage: /prefs [set <json> | clear]")
+
+    def app_data_command(ctx, args: list[str]) -> None:
+        runtime = ctx.runtime
+        if not args:
+            args = ["list"]
+
+        subcommand = args[0].lower()
+        if subcommand == "list":
+            data = runtime.list_app_data(ctx.session_id)
+            if data:
+                ctx.renderer.info(f"App data ({len(data)} entries):")
+                for entry in data:
+                    ctx.renderer.print(f"  {entry['key']}: {json.dumps(entry['value'])}")
+            else:
+                ctx.renderer.warn("No app data stored.")
+            return
+
+        if subcommand == "get":
+            if len(args) < 2:
+                ctx.renderer.error("Usage: /app_data get <key>")
+                return
+            key = args[1]
+            value = runtime.get_app_data(ctx.session_id, key)
+            if value is not None:
+                ctx.renderer.info(f"Value for '{key}':")
+                ctx.renderer.print(json.dumps(value, indent=2))
+            else:
+                ctx.renderer.warn(f"No data found for key: {key}")
+            return
+
+        if subcommand == "set":
+            if len(args) < 3:
+                ctx.renderer.error("Usage: /app_data set <key> <json>")
+                return
+            key = args[1]
+            try:
+                value = json.loads(" ".join(args[2:]))
+                runtime.set_app_data(ctx.session_id, key, value)
+                ctx.renderer.info(f"Data stored for key: {key}")
+            except json.JSONDecodeError as exc:
+                ctx.renderer.error(f"Invalid JSON: {exc}")
+            return
+
+        if subcommand == "delete":
+            if len(args) < 2:
+                ctx.renderer.error("Usage: /app_data delete <key>")
+                return
+            key = args[1]
+            deleted = runtime.delete_app_data(ctx.session_id, key)
+            if deleted:
+                ctx.renderer.info(f"Data deleted for key: {key}")
+            else:
+                ctx.renderer.warn(f"No data found for key: {key}")
+            return
+
+        ctx.renderer.error(f"Unknown subcommand: {subcommand}")
+        ctx.renderer.info(
+            "Usage: /app_data [list | get <key> | set <key> <json> | delete <key>]"
+        )
+
+    def history_command(ctx, args: list[str]) -> None:
+        limit = None
+        if args:
+            try:
+                limit = int(args[0])
+            except ValueError:
+                ctx.renderer.error("Limit must be a number")
+                return
+
+        turns = ctx.runtime.get_history_turns(ctx.session_id, limit=limit)
+        if not turns:
+            ctx.renderer.warn("No conversation history.")
+            return
+
+        ctx.renderer.info(f"Conversation history ({len(turns)} turns):")
+        for index, turn in enumerate(turns, 1):
+            ctx.renderer.print(f"\n--- Turn {index} ---")
+            ctx.renderer.print(f"User: {turn['user_message']}")
+            ctx.renderer.print(f"Agent: {turn['agent_response']}")
+
+    def compact_command(ctx, _args: list[str]) -> None:
+        summary_text, turn_id = ctx.runtime.compact_session(
+            ctx.session_id,
+            reason="manual",
+            session_total_tokens_reset=0,
+        )
+        if not summary_text:
+            ctx.renderer.warn("No conversation history to compact.")
+            return
+
+        ctx.renderer.info(f"Conversation compacted (turn_id={turn_id}).")
+        ctx.renderer.markdown(summary_text)
+
+    shell.command_registry.register(
+        Command(name="help", help="Show available commands", handler=help_command, aliases=("h", "?"))
+    )
+    shell.command_registry.register(
+        Command(name="exit", help="Exit the application", handler=exit_command, aliases=("quit", "q"))
+    )
+    shell.command_registry.register(
+        Command(name="clear", help="Clear the screen", handler=clear_command, aliases=("cls",))
+    )
+    shell.command_registry.register(
+        Command(name="session", help="Show current session info", handler=session_command)
+    )
+    shell.command_registry.register(
+        Command(name="prefs", help="View or set user preferences", handler=prefs_command)
+    )
+    shell.command_registry.register(
+        Command(name="app_data", help="Manage app-specific data", handler=app_data_command)
+    )
+    shell.command_registry.register(
+        Command(name="history", help="View conversation history", handler=history_command)
+    )
+    shell.command_registry.register(
+        Command(name="compact", help="Summarize conversation and save a checkpoint", handler=compact_command)
+    )

mash_cli-0.1.0/src/mash_cli/main.py

@@ -0,0 +1,39 @@
+"""Thin public CLI for package installation validation."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Sequence
+
+from mash import __version__, get_docs_url
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mash",
+        description="MashPy framework CLI.",
+        epilog=f"Documentation: {get_docs_url()}",
+    )
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="Show installed mashpy version and documentation URL.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        print(f"mashpy {__version__}")
+        print(f"Docs: {get_docs_url()}")
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mash_cli-0.1.0/src/mash_cli/render.py

@@ -0,0 +1,123 @@
+"""Console rendering for CLI applications."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, ContextManager, Generator, List, Optional, Protocol
+
+from rich import box
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+from rich.theme import Theme
+
+
+class Renderer(Protocol):
+    """Protocol for renderers."""
+
+    def info(self, text: str) -> None:
+        """Render informational text."""
+        ...
+
+    def warn(self, text: str) -> None:
+        """Render warning text."""
+        ...
+
+    def error(self, text: str) -> None:
+        """Render error text."""
+        ...
+
+    def markdown(self, text: str) -> None:
+        """Render Markdown-formatted text."""
+        ...
+
+    def table(self, headers: List[str], rows: List[List[str]]) -> None:
+        """Render a table."""
+        ...
+
+    def status(self, message: str) -> ContextManager[object]:
+        """Return a status spinner context manager."""
+        ...
+
+    def clear(self) -> None:
+        """Clear the terminal screen."""
+        ...
+
+
+class RichRenderer:
+    """Rich-based renderer for formatted CLI output."""
+
+    def __init__(self, console: Optional[Console] = None) -> None:
+        """Initialize renderer.
+
+        Args:
+            console: Rich console instance (creates new one if not provided).
+        """
+        theme = Theme(
+            {
+                "info": "bold cyan",
+                "warn": "bold yellow",
+                "error": "bold red",
+                "muted": "dim",
+            }
+        )
+        self._console = console or Console(theme=theme, soft_wrap=True)
+
+    @property
+    def console(self) -> Console:
+        """Get the underlying Rich console."""
+        return self._console
+
+    def info(self, text: str) -> None:
+        """Render informational text."""
+        self._console.print(text, style="info")
+
+    def warn(self, text: str) -> None:
+        """Render warning text."""
+        self._console.print(text, style="warn")
+
+    def error(self, text: str) -> None:
+        """Render error text."""
+        self._console.print(text, style="error")
+
+    def markdown(self, text: str) -> None:
+        """Render Markdown-formatted text."""
+        if not text.strip():
+            return
+
+        markdown = Markdown(text)
+        panel = Panel(
+            markdown,
+            title="Assistant",
+            border_style="cyan",
+            box=box.ASCII,
+            padding=(0, 1),
+        )
+        self._console.print(panel)
+
+    def table(self, headers: List[str], rows: List[List[str]]) -> None:
+        """Render a table."""
+        table = Table(box=box.ASCII)
+
+        for header in headers:
+            table.add_column(header, style="cyan")
+
+        for row in rows:
+            table.add_row(*row)
+
+        self._console.print(table)
+
+    @contextmanager
+    def status(self, message: str) -> Generator[object, None, None]:
+        """Return a status spinner context manager."""
+        with self._console.status(message) as status:
+            yield status
+
+    def clear(self) -> None:
+        """Clear the terminal screen."""
+        self._console.clear()
+
+    def print(self, *args: Any, **kwargs: Any) -> None:
+        """Print to console."""
+        self._console.print(*args, **kwargs)

mash_cli-0.1.0/src/mash_cli/repl.py

@@ -0,0 +1,124 @@
+"""Interactive REPL for CLI applications."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, List, Optional
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.patch_stdout import patch_stdout
+from prompt_toolkit.styles import Style
+
+if TYPE_CHECKING:
+    from .types import CLIContext
+    from .commands import CommandRegistry
+
+MessageHandler = Callable[["CLIContext", str], None]
+
+
+class REPL:
+    """Interactive read-eval-print loop."""
+
+    def __init__(
+        self,
+        app_id: str,
+        command_registry: CommandRegistry,
+        message_handler: Optional[MessageHandler] = None,
+    ) -> None:
+        """Initialize REPL.
+
+        Args:
+            app_id: Application ID for banner text and history file.
+            command_registry: Command registry for command completion.
+            message_handler: Handler for non-command messages.
+        """
+        self.app_id = app_id
+        self.command_registry = command_registry
+        self.message_handler = message_handler
+
+    def run(self, ctx: CLIContext) -> None:
+        """Run the REPL until user exits.
+
+        Args:
+            ctx: CLI context.
+        """
+        ctx.renderer.info(
+            f"{self.app_id} interactive session. Type /help for commands."
+        )
+
+        # Setup prompt
+        command_words = self._get_command_words()
+        completer = WordCompleter(command_words, ignore_case=True)
+        history = FileHistory(str(self._get_history_path()))
+        key_bindings = self._build_key_bindings(ctx)
+        prompt_style = Style.from_dict({"prompt": "bold cyan"})
+
+        session: PromptSession[str] = PromptSession(
+            history=history,
+            completer=completer,
+            auto_suggest=AutoSuggestFromHistory(),
+        )
+
+        # Main loop
+        while True:
+            try:
+                with patch_stdout():
+                    line = session.prompt(
+                        [("class:prompt", "> ")],
+                        style=prompt_style,
+                        key_bindings=key_bindings,
+                        complete_while_typing=True,
+                    )
+            except (KeyboardInterrupt, EOFError):
+                ctx.renderer.warn("Bye.")
+                return
+
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                # Handle commands
+                if line.startswith("/"):
+                    self.command_registry.execute(ctx, line)
+                # Handle messages
+                elif self.message_handler:
+                    with ctx.renderer.status("Thinking..."):
+                        self.message_handler(ctx, line)
+                else:
+                    ctx.renderer.warn("Only slash commands are supported. Try /help.")
+            except SystemExit:
+                ctx.renderer.warn("Bye.")
+                raise
+            except Exception as e:
+                ctx.renderer.error(f"Error: {str(e)}")
+
+    def _get_command_words(self) -> List[str]:
+        """Get list of command words for completion."""
+        words: List[str] = []
+        for command in self.command_registry.list_commands():
+            words.append(f"/{command.name}")
+            for alias in command.aliases:
+                words.append(f"/{alias}")
+        return sorted(set(words))
+
+    def _get_history_path(self) -> Path:
+        """Get path to history file."""
+        slug = "".join(ch.lower() if ch.isalnum() else "_" for ch in self.app_id)
+        slug = slug.strip("_") or "mash"
+        return Path(f".{slug}_history")
+
+    def _build_key_bindings(self, ctx: CLIContext) -> KeyBindings:
+        """Build key bindings for the REPL."""
+        bindings = KeyBindings()
+
+        @bindings.add("c-l")
+        def _clear_screen(_event: Any) -> None:
+            """Clear screen on Ctrl+L."""
+            ctx.renderer.clear()
+
+        return bindings

mash_cli-0.1.0/src/mash_cli/shell.py

@@ -0,0 +1,163 @@
+"""Composed CLI shell for Mash runtime engines."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from mash.core.context import Context, Response
+from mash.runtime.client import MashAgentClient
+from mash.runtime.definition import MashRuntimeDefinition
+from mash.runtime.host import MashAgentHost
+from mash.runtime.types import RuntimeTurnResult, SubAgentMetadata
+
+from .chain_renderer import ChainOfThoughtRenderer
+from .commands import Command, CommandRegistry
+from .default_commands import register_default_commands
+from .repl import REPL
+from .render import RichRenderer
+from .types import CLIContext
+
+
+@dataclass(frozen=True)
+class SubagentRegistration:
+    """Subagent registration payload for host-backed shell composition."""
+
+    definition: MashRuntimeDefinition
+    metadata: SubAgentMetadata
+    agent_id: str | None = None
+
+
+class CLIAppShell:
+    """Interactive shell backed by a host-managed primary agent client."""
+
+    def __init__(self, host: MashAgentHost, primary_agent_id: str) -> None:
+        self.host = host
+        self.primary_agent_id = primary_agent_id
+        self.client: MashAgentClient = host.get_client(primary_agent_id)
+        self.app_id = self.client.app_id
+
+        self.renderer = RichRenderer()
+        self.chain_renderer = ChainOfThoughtRenderer(console=self.renderer.console)
+        self.client.set_chain_renderer(self.chain_renderer)
+
+        self.command_registry = CommandRegistry(
+            app_id=self.client.app_id,
+            event_logger=self.client.get_event_logger(),
+            session_id=self.client.get_default_session_id(),
+        )
+        register_default_commands(self)
+
+        self.context = CLIContext(
+            app_id=self.client.app_id,
+            session_id=self.client.get_default_session_id(),
+            runtime=self.client,
+            renderer=self.renderer,
+        )
+
+    @classmethod
+    def from_definition(
+        cls,
+        definition: MashRuntimeDefinition,
+        *,
+        subagents: Sequence[SubagentRegistration] | None = None,
+        bind_host: str = "127.0.0.1",
+    ) -> CLIAppShell:
+        """Build a host-backed CLI shell from app definition(s)."""
+        host = MashAgentHost(bind_host=bind_host)
+        primary_agent_id = host.register_primary(definition)
+        for subagent in subagents or ():
+            host.register_subagent(
+                subagent.definition,
+                agent_id=subagent.agent_id,
+                metadata=subagent.metadata,
+            )
+        host.start()
+        return cls(host, primary_agent_id)
+
+    def register_command(self, command: Command) -> None:
+        """Register a custom CLI command."""
+        self.command_registry.register(command)
+
+    def handle_message(
+        self,
+        message: str,
+        session_id: str | None = None,
+    ) -> RuntimeTurnResult:
+        """Process one message via agent client and return structured turn output."""
+        target_session_id = (session_id or self.context.session_id).strip()
+        if not target_session_id:
+            target_session_id = self.context.session_id
+        payload = self.client.invoke(message, session_id=target_session_id)
+
+        response_payload = payload.get("response")
+        if isinstance(response_payload, dict):
+            text = str(response_payload.get("text") or "")
+            signals = response_payload.get("signals")
+            metadata = response_payload.get("metadata")
+        else:
+            text = str(payload.get("text") or "")
+            signals = payload.get("signals")
+            metadata = payload.get("metadata")
+
+        response = Response(
+            text=text,
+            context=Context(),
+            signals=signals if isinstance(signals, dict) else {},
+            metadata=metadata if isinstance(metadata, dict) else {},
+        )
+        session_value = str(payload.get("session_id") or target_session_id).strip()
+        if not session_value:
+            session_value = target_session_id
+
+        session_total_tokens = payload.get("session_total_tokens", 0)
+        try:
+            parsed_session_total_tokens = int(session_total_tokens)
+        except (TypeError, ValueError):
+            parsed_session_total_tokens = 0
+
+        compaction_summary_text = payload.get("compaction_summary_text")
+        compaction_summary_turn_id = payload.get("compaction_summary_turn_id")
+        return RuntimeTurnResult(
+            session_id=session_value,
+            response=response,
+            compaction_summary_text=(
+                compaction_summary_text if isinstance(compaction_summary_text, str) else None
+            ),
+            compaction_summary_turn_id=(
+                compaction_summary_turn_id if isinstance(compaction_summary_turn_id, str) else None
+            ),
+            session_total_tokens=parsed_session_total_tokens,
+        )
+
+    def render_turn_result(self, ctx: CLIContext, result: RuntimeTurnResult) -> None:
+        """Render runtime output to the terminal."""
+        if result.compaction_summary_text:
+            ctx.renderer.info("Compaction triggered - summary checkpoint created.")
+            ctx.renderer.markdown(result.compaction_summary_text)
+        if result.response.text:
+            ctx.renderer.markdown(result.response.text)
+
+    def handle_repl_message(self, ctx: CLIContext, message: str) -> None:
+        """REPL callback for non-command user input."""
+        result = self.handle_message(message, session_id=ctx.session_id)
+        self.render_turn_result(ctx, result)
+
+    def run(self) -> None:
+        """Run the interactive application."""
+        repl = REPL(
+            app_id=self.app_id,
+            command_registry=self.command_registry,
+            message_handler=self.handle_repl_message,
+        )
+
+        try:
+            repl.run(self.context)
+        except KeyboardInterrupt:
+            self.renderer.warn("\nBye.")
+        except SystemExit:
+            pass
+
+    def shutdown(self) -> None:
+        """Shutdown shell and runtime resources."""
+        self.host.close()

mash_cli-0.1.0/src/mash_cli/types.py

@@ -0,0 +1,19 @@
+"""CLI shell data types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mash.runtime.client import MashAgentClient
+
+from .render import RichRenderer
+
+
+@dataclass
+class CLIContext:
+    """Context for CLI operations."""
+
+    app_id: str
+    session_id: str
+    runtime: MashAgentClient
+    renderer: RichRenderer

mash_cli-0.1.0/src/mash_cli.egg-info/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: mash-cli
+Version: 0.1.0
+Summary: Interactive CLI shell package for Mash applications
+Author: imsid
+License: Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mashpy>=0.1.2
+Requires-Dist: prompt_toolkit>=3.0.36
+Requires-Dist: rich>=13.7.1
+
+# mash-cli
+
+Interactive CLI package for Mash applications.
+
+It provides:
+
+- `mash` console command
+- `mash_cli.CLIAppShell` and related command primitives for app shells
+
+Install options:
+
+- `pip install mash-cli`
+- `pip install "mashpy[cli]"`

mash_cli-0.1.0/src/mash_cli.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/mash_cli/__init__.py
+src/mash_cli/chain_renderer.py
+src/mash_cli/commands.py
+src/mash_cli/default_commands.py
+src/mash_cli/main.py
+src/mash_cli/render.py
+src/mash_cli/repl.py
+src/mash_cli/shell.py
+src/mash_cli/types.py
+src/mash_cli.egg-info/PKG-INFO
+src/mash_cli.egg-info/SOURCES.txt
+src/mash_cli.egg-info/dependency_links.txt
+src/mash_cli.egg-info/entry_points.txt
+src/mash_cli.egg-info/requires.txt
+src/mash_cli.egg-info/top_level.txt

mash_cli-0.1.0/src/mash_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mash_cli-0.1.0/src/mash_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mash = mash_cli.main:main

mash_cli-0.1.0/src/mash_cli.egg-info/requires.txt

@@ -0,0 +1,3 @@
+mashpy>=0.1.2
+prompt_toolkit>=3.0.36
+rich>=13.7.1

mash_cli-0.1.0/src/mash_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+mash_cli