monkeyscode 1.0.0__py3-none-any.whl

monkeyscode/export.py

@@ -0,0 +1,319 @@
+"""
+MonkeysCode SDK — Conversation Export.
+
+Export agent results as Markdown, HTML, or JSON transcript.
+
+Usage::
+
+    from monkeyscode.export import to_markdown, to_html, to_transcript
+
+    result = await agent.run("Fix all errors")
+
+    md = to_markdown(result)
+    html = to_html(result)
+    transcript = to_transcript(result)
+"""
+
+from __future__ import annotations
+
+import html as html_mod
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+from monkeyscode.events import AgentResult
+
+# ── Markdown Export ──────────────────────────────────────────────────
+
+
+def to_markdown(
+    result: AgentResult,
+    *,
+    title: str | None = None,
+    include_tool_calls: bool = True,
+    include_file_diffs: bool = True,
+    include_cost: bool = True,
+) -> str:
+    """Convert an agent result to a Markdown report."""
+    lines: list[str] = []
+
+    lines.append(f"# {title or 'MonkeysCode Agent Report'}")
+    lines.append("")
+
+    # Summary
+    lines.append("## Summary")
+    lines.append("")
+    status = "✅ Success" if result.success else "❌ Failed"
+    lines.append(f"- **Status**: {status}")
+    lines.append(f"- **Model**: {result.model or 'auto'}")
+    if result.session_id:
+        lines.append(f"- **Session**: `{result.session_id}`")
+    if result.duration_ms:
+        lines.append(f"- **Duration**: {_format_duration(result.duration_ms)}")
+    lines.append("")
+
+    # Agent output
+    if result.summary:
+        lines.append("## Agent Output")
+        lines.append("")
+        lines.append(result.summary)
+        lines.append("")
+
+    # Error
+    if result.error:
+        lines.append("## Error")
+        lines.append("")
+        lines.append(f"> {result.error}")
+        lines.append("")
+
+    # Files changed
+    if result.files_changed and include_file_diffs:
+        lines.append("## Files Changed")
+        lines.append("")
+        lines.append(f"{len(result.files_changed)} file(s) modified:")
+        lines.append("")
+        for f in result.files_changed:
+            lines.append(f"- `{f.path}` ({f.action})")
+            if f.diff:
+                lines.append("")
+                lines.append("```diff")
+                lines.append(f.diff)
+                lines.append("```")
+                lines.append("")
+
+    # Tool calls
+    if result.tool_calls and include_tool_calls:
+        lines.append("## Tool Calls")
+        lines.append("")
+        lines.append(f"{len(result.tool_calls)} tool call(s):")
+        lines.append("")
+        lines.append("| # | Tool | Duration |")
+        lines.append("|---|------|----------|")
+        for i, call in enumerate(result.tool_calls, 1):
+            if isinstance(call, dict):
+                tool_name = call.get("tool", "?")
+                duration = call.get("duration", 0)
+            else:
+                tool_name = getattr(call, "tool", "?")
+                duration = getattr(call, "duration", 0)
+            dur = f"{duration}ms" if duration else "—"
+            lines.append(f"| {i} | `{tool_name}` | {dur} |")
+        lines.append("")
+
+    # Cost
+    if include_cost and result.tokens:
+        lines.append("## Cost & Usage")
+        lines.append("")
+        lines.append("| Metric | Value |")
+        lines.append("|--------|-------|")
+        lines.append(f"| Cost | ${result.cost:.4f} |")
+        lines.append(f"| Input tokens | {result.tokens.input:,} |")
+        lines.append(f"| Output tokens | {result.tokens.output:,} |")
+        if result.tokens.thinking:
+            lines.append(f"| Thinking tokens | {result.tokens.thinking:,} |")
+        lines.append(f"| Total tokens | {result.tokens.total:,} |")
+        lines.append("")
+
+    # Footer
+    lines.append("---")
+    lines.append(f"*Generated by MonkeysCode SDK at {datetime.now(timezone.utc).isoformat()}*")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+# ── HTML Export ──────────────────────────────────────────────────────
+
+
+def to_html(
+    result: AgentResult,
+    *,
+    title: str | None = None,
+    **kwargs: Any,
+) -> str:
+    """Convert an agent result to a styled HTML report."""
+    md = to_markdown(result, title=title, **kwargs)
+    escaped_title = html_mod.escape(title or "MonkeysCode Agent Report")
+    body = _markdown_to_html(md)
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{escaped_title}</title>
+<style>
+:root {{
+  --bg: #0d1117;
+  --fg: #e6edf3;
+  --accent: #58a6ff;
+  --success: #3fb950;
+  --error: #f85149;
+  --border: #30363d;
+  --code-bg: #161b22;
+}}
+* {{ box-sizing: border-box; }}
+body {{
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  background: var(--bg);
+  color: var(--fg);
+  max-width: 860px;
+  margin: 0 auto;
+  padding: 2rem 1.5rem;
+  line-height: 1.6;
+}}
+h1 {{ border-bottom: 1px solid var(--border); padding-bottom: 0.5em; color: var(--accent); }}
+h2 {{ margin-top: 2em; }}
+code {{ background: var(--code-bg); padding: 0.2em 0.4em; border-radius: 4px; font-size: 0.9em; }}
+pre {{ background: var(--code-bg); padding: 1em; border-radius: 8px; overflow-x: auto; }}
+pre code {{ background: none; padding: 0; }}
+table {{ width: 100%; border-collapse: collapse; margin: 1em 0; }}
+th, td {{ padding: 0.5em 0.75em; text-align: left; border: 1px solid var(--border); }}
+th {{ background: var(--code-bg); }}
+blockquote {{ border-left: 3px solid var(--error); padding-left: 1em; color: var(--error); }}
+hr {{ border: none; border-top: 1px solid var(--border); margin: 2em 0; }}
+em {{ color: #8b949e; }}
+</style>
+</head>
+<body>
+{body}
+</body>
+</html>"""
+
+
+# ── Transcript Export ────────────────────────────────────────────────
+
+
+def to_transcript(
+    result: AgentResult,
+    events: list[Any] | None = None,
+) -> dict[str, Any]:
+    """Export the full result as a structured JSON transcript."""
+    return {
+        "version": "1.0",
+        "exported_at": datetime.now(timezone.utc).isoformat(),
+        "result": {
+            "success": result.success,
+            "status": result.status,
+            "summary": result.summary,
+            "model": result.model,
+            "cost": result.cost,
+            "duration_ms": result.duration_ms,
+            "tokens": {
+                "input": result.tokens.input if result.tokens else 0,
+                "output": result.tokens.output if result.tokens else 0,
+                "thinking": result.tokens.thinking if result.tokens else 0,
+                "total": result.tokens.total if result.tokens else 0,
+            },
+            "files_changed": [
+                {"path": f.path, "action": f.action}
+                for f in (result.files_changed or [])
+            ],
+        },
+        "events": events,
+    }
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+
+def _format_duration(ms: float) -> str:
+    if ms < 1000:
+        return f"{ms:.0f}ms"
+    if ms < 60_000:
+        return f"{ms / 1000:.1f}s"
+    mins = int(ms // 60_000)
+    secs = round((ms % 60_000) / 1000)
+    return f"{mins}m {secs}s"
+
+
+def _markdown_to_html(md: str) -> str:
+    """Minimal Markdown → HTML converter (no dependencies)."""
+    lines = md.split("\n")
+    out: list[str] = []
+    in_code = False
+    in_table = False
+    in_list = False
+
+    for line in lines:
+        if line.startswith("```"):
+            if in_code:
+                out.append("</code></pre>")
+                in_code = False
+            else:
+                lang = line[3:].strip() or "text"
+                out.append(f'<pre><code class="language-{lang}">')
+                in_code = True
+            continue
+        if in_code:
+            out.append(html_mod.escape(line))
+            continue
+
+        if in_table and not line.startswith("|"):
+            out.append("</tbody></table>")
+            in_table = False
+        if in_list and not line.startswith("- "):
+            out.append("</ul>")
+            in_list = False
+
+        stripped = line.strip()
+        if not stripped:
+            out.append("")
+            continue
+
+        # Headings
+        m = re.match(r"^(#{1,6})\s+(.+)", line)
+        if m:
+            level = len(m.group(1))
+            out.append(f"<h{level}>{_inline(m.group(2))}</h{level}>")
+            continue
+
+        if re.match(r"^---+$", stripped):
+            out.append("<hr>")
+            continue
+
+        if stripped.startswith("> "):
+            out.append(f"<blockquote>{_inline(stripped[2:])}</blockquote>")
+            continue
+
+        if stripped.startswith("|"):
+            if re.match(r"^\|[\s\-|]+\|$", stripped):
+                continue
+            cells = [c.strip() for c in stripped.split("|") if c.strip()]
+            if not in_table:
+                out.append("<table><thead><tr>")
+                out.extend(f"<th>{_inline(c)}</th>" for c in cells)
+                out.append("</tr></thead><tbody>")
+                in_table = True
+            else:
+                out.append("<tr>")
+                out.extend(f"<td>{_inline(c)}</td>" for c in cells)
+                out.append("</tr>")
+            continue
+
+        if stripped.startswith("- "):
+            if not in_list:
+                out.append("<ul>")
+                in_list = True
+            out.append(f"<li>{_inline(stripped[2:])}</li>")
+            continue
+
+        out.append(f"<p>{_inline(line)}</p>")
+
+    if in_code:
+        out.append("</code></pre>")
+    if in_table:
+        out.append("</tbody></table>")
+    if in_list:
+        out.append("</ul>")
+
+    return "\n".join(out)
+
+
+def _inline(text: str) -> str:
+    """Convert inline markdown."""
+    text = html_mod.escape(text)
+    text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", text)
+    text = re.sub(r"`(.+?)`", r"<code>\1</code>", text)
+    text = re.sub(r"\*(.+?)\*", r"<em>\1</em>", text)
+    return text

monkeyscode/hooks.py

@@ -0,0 +1,190 @@
+"""
+MonkeysCode SDK — Hooks System.
+
+Intercept, modify, or block tool calls before/after execution.
+Matches Claude Agent SDK's PreToolUse / PostToolUse pattern.
+
+Usage::
+
+    from monkeyscode import MonkeysCode
+
+    agent = MonkeysCode(api_key="mc_...")
+
+    @agent.on_pre_tool_use
+    async def block_destructive(ctx):
+        if ctx.tool == "shell_command" and "rm -rf" in (ctx.args.get("command") or ""):
+            return PreToolResult(action="block", reason="Destructive command blocked")
+        return PreToolResult(action="allow")
+
+    @agent.on_post_tool_use
+    async def log_tools(ctx):
+        print(f"{ctx.tool}: {'FAIL' if ctx.is_error else 'OK'} ({ctx.duration_ms}ms)")
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+logger = logging.getLogger("monkeyscode.hooks")
+
+# ── Types ────────────────────────────────────────────────────────────
+
+HookAction = Literal["allow", "block", "modify"]
+
+
+@dataclass
+class PreToolContext:
+    """Context passed to pre-tool hooks."""
+
+    tool: str
+    args: dict[str, Any]
+    run_id: str
+    turn_index: int
+    session_id: str | None = None
+    timestamp: float = 0.0
+
+
+@dataclass
+class PreToolResult:
+    """Result from a pre-tool hook."""
+
+    action: HookAction = "allow"
+    args: dict[str, Any] | None = None  # for 'modify'
+    reason: str | None = None  # for 'block'
+
+
+@dataclass
+class PostToolContext:
+    """Context passed to post-tool hooks."""
+
+    tool: str
+    args: dict[str, Any]
+    result: Any
+    is_error: bool
+    duration_ms: float
+    run_id: str
+    turn_index: int
+    session_id: str | None = None
+    timestamp: float = 0.0
+
+
+PreToolHook = Callable[[PreToolContext], Awaitable[PreToolResult] | PreToolResult]
+PostToolHook = Callable[[PostToolContext], Awaitable[None] | None]
+
+
+# ── Hook Manager ─────────────────────────────────────────────────────
+
+
+class HookManager:
+    """
+    Manages pre- and post-tool hooks for an agent instance.
+
+    Hook execution order:
+    1. All pre-hooks run in registration order
+    2. First hook to return 'block' wins (short-circuits)
+    3. Last hook to return 'modify' wins (args are cumulative)
+    4. Tool executes (or is blocked)
+    5. All post-hooks run in registration order (fire-and-forget)
+    """
+
+    def __init__(self) -> None:
+        self._pre_hooks: list[PreToolHook] = []
+        self._post_hooks: list[PostToolHook] = []
+
+    @property
+    def has_hooks(self) -> bool:
+        """Whether any hooks are registered."""
+        return bool(self._pre_hooks or self._post_hooks)
+
+    @property
+    def pre_hook_count(self) -> int:
+        return len(self._pre_hooks)
+
+    @property
+    def post_hook_count(self) -> int:
+        return len(self._post_hooks)
+
+    def add_pre_hook(self, hook: PreToolHook) -> None:
+        """Register a pre-tool hook."""
+        self._pre_hooks.append(hook)
+
+    def add_post_hook(self, hook: PostToolHook) -> None:
+        """Register a post-tool hook."""
+        self._post_hooks.append(hook)
+
+    def remove_pre_hook(self, hook: PreToolHook) -> bool:
+        """Remove a pre-tool hook. Returns True if found."""
+        try:
+            self._pre_hooks.remove(hook)
+            return True
+        except ValueError:
+            return False
+
+    def remove_post_hook(self, hook: PostToolHook) -> bool:
+        """Remove a post-tool hook. Returns True if found."""
+        try:
+            self._post_hooks.remove(hook)
+            return True
+        except ValueError:
+            return False
+
+    def clear_all(self) -> None:
+        """Remove all hooks."""
+        self._pre_hooks.clear()
+        self._post_hooks.clear()
+
+    async def run_pre_hooks(self, context: PreToolContext) -> PreToolResult:
+        """
+        Run all pre-tool hooks in order.
+
+        - First 'block' result short-circuits and returns it.
+        - 'modify' results accumulate.
+        - If all return 'allow', returns PreToolResult(action='allow').
+        """
+        if not self._pre_hooks:
+            return PreToolResult(action="allow")
+
+        current_args = dict(context.args)
+        last_modify: PreToolResult | None = None
+
+        for hook in self._pre_hooks:
+            try:
+                result = hook(PreToolContext(
+                    tool=context.tool,
+                    args=current_args,
+                    run_id=context.run_id,
+                    turn_index=context.turn_index,
+                    session_id=context.session_id,
+                    timestamp=context.timestamp,
+                ))
+                # Await if coroutine
+                if hasattr(result, "__await__"):
+                    result = await result  # type: ignore[misc]
+
+                if result.action == "block":
+                    return result
+
+                if result.action == "modify" and result.args is not None:
+                    current_args.update(result.args)
+                    last_modify = PreToolResult(action="modify", args=dict(current_args))
+
+            except Exception:
+                logger.exception("Pre-hook error (tool: %s)", context.tool)
+
+        if last_modify:
+            return last_modify
+
+        return PreToolResult(action="allow")
+
+    async def run_post_hooks(self, context: PostToolContext) -> None:
+        """Run all post-tool hooks. Errors are logged, never raised."""
+        for hook in self._post_hooks:
+            try:
+                result = hook(context)
+                if hasattr(result, "__await__"):
+                    await result  # type: ignore[misc]
+            except Exception:
+                logger.exception("Post-hook error (tool: %s)", context.tool)