intentos 0.4.1__tar.gz → 0.4.2__tar.gz

{intentos-0.4.1 → intentos-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: intentos
-Version: 0.4.1
+Version: 0.4.2
 Summary: An open interoperability layer for AI capabilities, workflows, and execution
 Author: Intent OS Project
 License-Expression: MIT

{intentos-0.4.1 → intentos-0.4.2}/cli.py

@@ -23,6 +23,8 @@ import commands.evolution
 import commands.ask
 import commands.demo
 import commands.trace
+import commands.proxy
+import commands.doctor
 
 # All cmd_* functions are imported from command modules via the registry pattern below
 CMD_MAP = {
@@ -42,6 +44,8 @@ CMD_MAP = {
     "ask": commands.ask.cmd_ask,
     "demo": commands.demo.cmd_demo,
     "inspect": commands.trace.cmd_inspect,
+    "proxy": commands.proxy.cmd_proxy,
+    "doctor": commands.doctor.cmd_doctor,
 }
 
 def build_parser() -> argparse.ArgumentParser:
@@ -51,7 +55,7 @@ def build_parser() -> argparse.ArgumentParser:
         description="Intent OS Reference Runtime - Open AI Capability Interoperability",
         epilog="Phase 0 - Prove that one Manifest can run on multiple runtimes.",
     )
-    parser.add_argument("--version", action="version", version="intent-os 0.4.1")
+    parser.add_argument("--version", action="version", version="intent-os 0.4.2")
 
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
 
@@ -235,6 +239,24 @@ def build_parser() -> argparse.ArgumentParser:
                                 help="Export trace as a standalone HTML file for sharing")
     inspect_parser.set_defaults(func=CMD_MAP["inspect"])
 
+    # proxy
+    proxy_parser = subparsers.add_parser("proxy",
+        help="Start the Agent Hook proxy to record AI agent API calls")
+    proxy_sub = proxy_parser.add_subparsers(dest="proxy_action", help="Proxy actions")
+    ps = proxy_sub.add_parser("start", help="Start the proxy server")
+    ps.add_argument("--port", type=int, default=8377, help="Port (default: 8377)")
+    ps.add_argument("--host", default="127.0.0.1", help="Host (default: 127.0.0.1)")
+    ps.set_defaults(func=CMD_MAP["proxy"])
+    pst = proxy_sub.add_parser("status", help="Check if the proxy is running")
+    pst.add_argument("--port", type=int, default=8377, help="Port (default: 8377)")
+    pst.add_argument("--host", default="127.0.0.1", help="Host (default: 127.0.0.1)")
+    pst.set_defaults(func=CMD_MAP["proxy"])
+
+    # doctor
+    doctor_parser = subparsers.add_parser("doctor",
+        help="Check your AI agent's health — see what happened, what went wrong, and how to fix it")
+    doctor_parser.set_defaults(func=CMD_MAP["doctor"])
+
     return parser
 
 

intentos-0.4.2/commands/doctor.py

@@ -0,0 +1,210 @@
+"""Intent OS — doctor command: AI Agent Health Report.
+
+The first thing a user runs when something feels wrong.
+No understanding of traces, events, or manifests required.
+
+    intent-os doctor
+
+Shows whether the last agent run succeeded or failed,
+what went wrong, and how to fix it.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from commands.helpers import get_event_store, setup_executor, find_builtin_manifest
+
+_project_root = Path(__file__).parent.parent
+if str(_project_root) not in sys.path:
+    sys.path.insert(0, str(_project_root))
+
+
+def _get_agent_status(record: dict[str, Any] | None) -> str:
+    """Classify the agent's last run as healthy, failed, or unknown."""
+    if record is None:
+        return "unknown"
+    status = record.get("status", "")
+    if status == "success":
+        return "healthy"
+    elif status == "failure":
+        return "failed"
+    elif status == "partial":
+        return "partial"
+    return "unknown"
+
+
+def _summarize_failure(events: list[dict[str, Any]], record: dict[str, Any] | None) -> dict[str, Any]:
+    """Analyze failure: find the failed step and reason."""
+    result = {
+        "failed_events": [],
+        "error_message": None,
+        "suggestion": None,
+        "failed_at": None,
+    }
+
+    if record and record.get("error"):
+        result["error_message"] = record["error"]
+
+    # Scan events for failures
+    for evt in events:
+        etype = evt.get("event_type", "")
+        if etype in ("TaskFailed", "WorkflowFailed"):
+            cap = evt.get("capability", "")
+            source = evt.get("source", "")
+            result["failed_events"].append(f"{cap} ({source})")
+            result["failed_at"] = cap or source or "unknown"
+
+            # Extract error from payload (stored as JSON string in Event Store)
+            raw_payload = evt.get("payload", "{}")
+            if isinstance(raw_payload, str):
+                import json
+                try:
+                    payload = json.loads(raw_payload)
+                except json.JSONDecodeError:
+                    payload = {}
+            else:
+                payload = raw_payload
+            if isinstance(payload, dict) and payload.get("error_message"):
+                result["error_message"] = payload["error_message"]
+
+    # Generate suggestion from error patterns
+    err = (result["error_message"] or "").lower()
+    if "timeout" in err or "timed out" in err:
+        result["suggestion"] = "Increase timeout duration or retry with a simpler request."
+    elif "rate limit" in err or "429" in err:
+        result["suggestion"] = "You're being rate-limited. Slow down requests or check your API plan."
+    elif "authentication" in err or "api key" in err or "unauthorized" in err:
+        result["suggestion"] = "Check that your API key is set and valid."
+    elif "context" in err and ("length" in err or "token" in err):
+        result["suggestion"] = "The input was too long. Try a shorter prompt or use a model with larger context."
+    elif "connect" in err or "connection" in err:
+        result["suggestion"] = "Could not reach the API. Check your network or if the service is down."
+    elif "permission" in err or "denied" in err or "forbidden" in err:
+        result["suggestion"] = "Permission denied. Check file permissions or access rights."
+    elif "not found" in err or "no such" in err:
+        result["suggestion"] = "A required file or resource was not found. Check the path exists."
+    elif "server error" in err or "500" in err or "502" in err or "503" in err:
+        result["suggestion"] = "The API server returned an error. This is usually temporary — try again."
+    else:
+        result["suggestion"] = "Check the full trace for details."
+
+    return result
+
+
+def _suggest_next_step(record: dict[str, Any] | None) -> str:
+    """Suggest what the user should do next."""
+    if record is None:
+        return "Run a capability first:  intent-os run translate -p text=hello -p target_lang=zh"
+    return "View full trace:           intent-os inspect latest"
+
+
+def cmd_doctor(args: Any) -> None:
+    """Check the health of your last AI agent execution.
+
+    Analyzes the most recent execution record and tells you:
+    - Did it succeed or fail?
+    - What went wrong?
+    - How to fix it?
+    - How much it cost?
+    """
+    store = get_event_store()
+    all_ids = store.get_all_trace_ids()
+
+    if not all_ids:
+        # No traces yet — guide the user to create one
+        print()
+        print("  ================================================")
+        print("    Intent OS Doctor - Health Check")
+        print("  ================================================")
+        print()
+        print("  No agent executions found.")
+        print()
+        print("  Run a demo to see how it works:")
+        print("    intent-os demo --auto")
+        print()
+        print("  Or run a capability:")
+        print("    intent-os run translate -p text=hello -p target_lang=zh")
+        print()
+        print("  Want to record your own AI agent?")
+        print("    intent-os proxy start")
+        print()
+        return
+
+    # Get latest trace
+    trace_id = all_ids[0]
+    record = store.get_record(trace_id)
+    events = store.get_events_by_trace(trace_id)
+
+    status = _get_agent_status(record)
+
+    print()
+    print("  ================================================")
+    print("    Intent OS Doctor - Health Check")
+    print("  ================================================")
+    print()
+
+    if status == "healthy":
+        name = record.get("manifest_name", "?") if record else "?"
+        version = record.get("manifest_version", "?") if record else "?"
+        runtime = record.get("runtime_id", "?") if record else "?"
+        adapter = record.get("adapter", "?") if record else "?"
+        latency = record.get("total_latency_ms", 0) if record else 0
+        cost = record.get("total_cost_usd", 0.0) if record else 0.0
+        tokens = record.get("total_tokens", 0) if record else 0
+
+        print(f"  [OK]  Last Agent Run: Healthy")
+        print()
+        print(f"  Capability:")
+        print(f"    {name}@{version}")
+        print()
+        print(f"  Runtime:     {runtime} ({adapter})")
+        print(f"  Duration:    {latency:.0f}ms")
+        print(f"  Steps:       {len(events)}")
+        print(f"  Cost:        ${cost:.4f}")
+        print(f"  Tokens:      {tokens}")
+
+    elif status == "failed":
+        name = record.get("manifest_name", "?") if record else "?"
+        analysis = _summarize_failure(events, record)
+
+        print(f"  [!!]  Last Agent Run: Failed")
+        print()
+        print(f"  Capability:  {name}")
+
+        if analysis["failed_at"]:
+            print(f"  Failed at:   {analysis['failed_at']}")
+
+        print()
+        print("  Problem:")
+        print(f"    {analysis['error_message'] or 'Unknown error'}")
+        print()
+
+        if analysis["failed_events"]:
+            print("  Failed events:")
+            for fe in analysis["failed_events"]:
+                print(f"    - {fe}")
+            print()
+
+        if analysis["suggestion"]:
+            print("  Suggestion:")
+            print(f"    {analysis['suggestion']}")
+            print()
+
+    elif status == "partial":
+        print(f"  [..]  Last Agent Run: Partial")
+        print()
+        print("  Some steps succeeded, some failed.")
+
+    else:
+        print(f"  [?]   Last Agent Run: Unknown")
+        print()
+
+    # Next step suggestion
+    print()
+    next_step = _suggest_next_step(record)
+    print(f"  {'=' * 48}")
+    print(f"  {next_step}")
+    print(f"  {'=' * 48}")
+    print()

intentos-0.4.2/commands/proxy.py

@@ -0,0 +1,84 @@
+"""Intent OS CLI — proxy command: Agent Hook proxy server."""
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+
+def cmd_proxy(args: Any) -> None:
+    """Start or manage the Agent Hook proxy server.
+
+    The proxy intercepts OpenAI and Anthropic API calls from AI coding
+    agents (Claude Code, Cursor, Copilot, etc.) and records every call
+    to the Intent OS Event Store for later inspection.
+    """
+    action = args.proxy_action
+
+    if action == "start":
+        _cmd_start(args)
+    elif action == "status":
+        _cmd_status(args)
+    else:
+        print(f"Unknown proxy action: {action}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_start(args: Any) -> None:
+    """Start the proxy server."""
+    from proxy.server import start_proxy
+
+    port = getattr(args, "port", 8377)
+    host = getattr(args, "host", "127.0.0.1")
+
+    print()
+    print("  ================================================")
+    print("    Intent OS Agent Hook Proxy")
+    print("  ================================================")
+    print()
+    print(f"  Proxy listening on http://{host}:{port}")
+    print()
+    print("  Connect your AI agent:")
+    print()
+    print(f"    export OPENAI_BASE_URL=http://{host}:{port}")
+    print(f"    export ANTHROPIC_BASE_URL=http://{host}:{port}")
+    print()
+    print("  Then restart your agent. All executions will be recorded.")
+    print()
+    print("  Check your agent's health with:  intent-os doctor")
+    print()
+
+    try:
+        server = start_proxy(port=port, host=host)
+        server.serve_forever()
+    except PermissionError:
+        print(f"  Error: Permission denied for port {port}.", file=sys.stderr)
+        print(f"  Try a higher port: intent-os proxy start --port 8377", file=sys.stderr)
+        sys.exit(1)
+    except OSError as exc:
+        print(f"  Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_status(args: Any) -> None:
+    """Check if the proxy server is running."""
+    import socket
+
+    port = getattr(args, "port", 8377)
+    host = getattr(args, "host", "127.0.0.1")
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.settimeout(2)
+        result = sock.connect_ex((host, port))
+        if result == 0:
+            print(f"  Agent Hook Proxy is RUNNING on http://{host}:{port}")
+            print()
+            print("  To view captured traces:")
+            print("    intent-os inspect latest")
+        else:
+            print(f"  Agent Hook Proxy is NOT running on http://{host}:{port}")
+            print()
+            print("  To start:")
+            print(f"    intent-os proxy start --port {port}")
+    finally:
+        sock.close()

{intentos-0.4.1 → intentos-0.4.2}/core/event_store.py

@@ -34,7 +34,7 @@ from core.recorder import ExecutionRecorder
 
 
 # Schema version to support future migrations
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 
 # SQL statements for table creation
 CREATE_EVENTS_TABLE = """
@@ -97,6 +97,18 @@ CREATE TABLE IF NOT EXISTS meta (
 );
 """
 
+CREATE_TASK_STATE_TABLE = """
+CREATE TABLE IF NOT EXISTS task_state (
+    trace_id TEXT NOT NULL,
+    task_id TEXT NOT NULL,
+    workflow_id TEXT NOT NULL DEFAULT '',
+    field_name TEXT NOT NULL,
+    field_value TEXT NOT NULL DEFAULT '{}',
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (trace_id, task_id, field_name)
+);
+"""
+
 
 class EventStoreError(Exception):
     """Raised when Event Store operations fail."""
@@ -154,6 +166,7 @@ class EventStore:
         conn = self._get_conn()
         conn.execute(CREATE_EVENTS_TABLE)
         conn.execute(CREATE_EXECUTION_RECORDS_TABLE)
+        conn.execute(CREATE_TASK_STATE_TABLE)
         conn.execute(CREATE_META_TABLE)
         for idx in CREATE_INDEXES:
             try:
@@ -517,6 +530,113 @@ class EventStore:
         cursor = conn.execute(sql, params)
         return [dict(row) for row in cursor.fetchall()]
 
+    # ── Task State (Data Plane storage for Scheduler) ──
+
+    def save_task_state(
+        self,
+        trace_id: str,
+        task_id: str,
+        field_name: str,
+        field_value: str,
+        workflow_id: str = "",
+    ) -> None:
+        """Persist a single task state field to the Data Plane.
+
+        This is how the Scheduler satisfies R1 (Control Plane owns no
+        state) — instead of holding ``_task_outputs`` in memory, the
+        Scheduler writes each field as a row in the ``task_state`` table.
+        """
+        conn = self._get_conn()
+        conn.execute(
+            """INSERT OR REPLACE INTO task_state
+               (trace_id, task_id, workflow_id, field_name, field_value, updated_at)
+               VALUES (?, ?, ?, ?, ?, datetime('now'))""",
+            (trace_id, task_id, workflow_id, field_name, json.dumps(field_value)),
+        )
+        conn.commit()
+
+    def save_task_output(
+        self,
+        trace_id: str,
+        task_id: str,
+        output: dict[str, Any],
+        workflow_id: str = "",
+    ) -> None:
+        """Convenience: save a task's output dict as the ``output`` field."""
+        self.save_task_state(trace_id, task_id, "output", output, workflow_id)
+
+    def save_task_error(
+        self,
+        trace_id: str,
+        task_id: str,
+        error: str,
+        workflow_id: str = "",
+    ) -> None:
+        """Convenience: save a task's error as the ``error`` field."""
+        self.save_task_state(trace_id, task_id, "error", error, workflow_id)
+
+    def get_task_state(
+        self,
+        trace_id: str,
+        task_id: str,
+        field_name: str,
+    ) -> Any:
+        """Read a single task state field from the Data Plane."""
+        conn = self._get_conn()
+        cursor = conn.execute(
+            """SELECT field_value FROM task_state
+               WHERE trace_id = ? AND task_id = ? AND field_name = ?""",
+            (trace_id, task_id, field_name),
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        try:
+            return json.loads(row["field_value"])
+        except (json.JSONDecodeError, TypeError):
+            return row["field_value"]
+
+    def get_all_task_outputs(self, trace_id: str) -> dict[str, Any]:
+        """Read all task outputs for a trace (used by Scheduler for condition evaluation)."""
+        conn = self._get_conn()
+        cursor = conn.execute(
+            """SELECT task_id, field_value FROM task_state
+               WHERE trace_id = ? AND field_name = 'output'""",
+            (trace_id,),
+        )
+        result: dict[str, Any] = {}
+        for row in cursor.fetchall():
+            try:
+                result[row["task_id"]] = json.loads(row["field_value"])
+            except (json.JSONDecodeError, TypeError):
+                result[row["task_id"]] = row["field_value"]
+        return result
+
+    def get_all_task_errors(self, trace_id: str) -> dict[str, str]:
+        """Read all task errors for a trace."""
+        conn = self._get_conn()
+        cursor = conn.execute(
+            """SELECT task_id, field_value FROM task_state
+               WHERE trace_id = ? AND field_name = 'error'""",
+            (trace_id,),
+        )
+        result: dict[str, str] = {}
+        for row in cursor.fetchall():
+            try:
+                val = json.loads(row["field_value"])
+                result[row["task_id"]] = str(val)
+            except (json.JSONDecodeError, TypeError):
+                result[row["task_id"]] = str(row["field_value"])
+        return result
+
+    def delete_task_state(self, trace_id: str) -> None:
+        """Clean up task state for a trace when it's no longer needed."""
+        conn = self._get_conn()
+        conn.execute("DELETE FROM task_state WHERE trace_id = ?", (trace_id,))
+        conn.commit()
+
+    # ── Legacy query interface ──
+
     def get_all_trace_ids(self) -> list[str]:
         """List all trace IDs in the store."""
         conn = self._get_conn()