@invokehq/cli 0.2.6 → 0.2.8

package/README.md

@@ -30,7 +30,7 @@ invoke init support-agent --template crm-guardrail
 cd support-agent
 
 # 4. Run its local MCP server
-invoke dev
+invoke dev install
 
 # 5. Register its tools with Invoke
 invoke deploy

package/agentify.py

@@ -1165,6 +1165,18 @@ def sample_sdk_source() -> str:
 def init_command(args: argparse.Namespace) -> int:
     root = Path(args.name)
     project_name = root.name
+
+    if args.template == "claude-agent":
+        from invoke.deploy import copy_template
+
+        path = copy_template(root, force=args.force)
+        print(f"Created Claude Agent SDK project at {path}")
+        print("Next:")
+        print(f"  cd {path}")
+        print("  npm install")
+        print("  invoke deploy --dry-run")
+        return 0
+
     if root.exists() and any(root.iterdir()) and not args.force:
         raise ValueError(f"{root} already exists and is not empty. Pass --force to write into it.")
     root.mkdir(parents=True, exist_ok=True)
@@ -1214,6 +1226,31 @@ def read_project(root: Path) -> dict[str, Any]:
     return config
 
 
+def read_project_config(root: Path) -> dict[str, Any]:
+    config_path = root / "invoke.json"
+    if not config_path.exists():
+        return {}
+    config = load_json_file(config_path, {})
+    if not isinstance(config, dict):
+        raise ValueError("invoke.json must contain an object")
+    return config
+
+
+def is_agent_project(root: Path, config: dict[str, Any]) -> bool:
+    runtime = str(config.get("runtime") or "").lower()
+    agent_type = str(config.get("agent_type") or config.get("type") or "").lower()
+    has_entrypoint = bool(config.get("entrypoint")) or any(
+        (root / candidate).exists() for candidate in ("src/index.ts", "src/index.js", "index.ts", "index.js")
+    )
+    tools = config.get("tools")
+    empty_tools = tools is None or tools == []
+    return has_entrypoint and (
+        runtime in {"node", "python", "claude-agent-sdk"}
+        or agent_type in {"agent", "claude-agent", "claude-agent-sdk"}
+        or empty_tools
+    )
+
+
 def project_mcp_url(root: Path, config: dict[str, Any], explicit_mcp_url: str | None = None) -> str | None:
     if explicit_mcp_url:
         return explicit_mcp_url
@@ -1371,6 +1408,35 @@ def save_deployment(record: dict[str, Any]) -> None:
 
 def deploy_command(args: argparse.Namespace) -> int:
     root = Path(args.path)
+    raw_config = read_project_config(root)
+    if is_agent_project(root, raw_config):
+        from dataclasses import asdict
+
+        from invoke.deploy import deploy_claude_agent
+
+        result = deploy_claude_agent(
+            root,
+            app_name=args.slug or raw_config.get("slug") or raw_config.get("name"),
+            dry_run=args.dry_run,
+        )
+        record = {
+            "project": str(root.resolve()),
+            "name": result.plan.app_name,
+            "provider_id": result.deployment_id,
+            "slug": result.plan.app_name,
+            "gateway_url": result.endpoint_url,
+            "dashboard_url": result.dashboard_url,
+            "base_url": "modal",
+            "tools": ["agent.run"],
+            "deployed_at": dt.datetime.now(dt.timezone.utc).isoformat(),
+            "mode": "modal_agent",
+            "trace_path": result.trace_path,
+        }
+        if not args.dry_run:
+            save_deployment(record)
+        print(json.dumps({"success": result.success, "mode": "modal_agent", **asdict(result)}, indent=2))
+        return 0
+
     config = read_project(root)
     tools = config["tools"]
     mcp_url = project_mcp_url(root, config, args.mcp_url)
@@ -1773,7 +1839,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     init = subparsers.add_parser("init", help="Scaffold an Invoke project.")
     init.add_argument("name", help="Project directory/name.")
-    init.add_argument("--template", choices=["default", "linear", "crm-guardrail"], default="default")
+    init.add_argument("--template", choices=["default", "linear", "crm-guardrail", "claude-agent"], default="default")
     init.add_argument("--force", action="store_true", help="Write into an existing non-empty directory.")
     init.set_defaults(func=init_command)
 

package/invoke/__init__.py

@@ -0,0 +1,5 @@
+"""Invoke agent deployment and supervision primitives."""
+
+from .deploy import DeployPlan, DeployResult, deploy_claude_agent
+
+__all__ = ["DeployPlan", "DeployResult", "deploy_claude_agent"]

package/invoke/deploy.py

@@ -0,0 +1,243 @@
+"""Modal-backed deployment planning for Claude Agent SDK projects.
+
+This module is intentionally small and import-safe. The public CLI can call
+`deploy_claude_agent(path)` without importing Modal unless the caller actually
+wants to deploy. That lets the local CLI stay lightweight while giving us a
+real place to evolve hosted agent deployment.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import shutil
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .onyx.analyzer import OnyxSuggestion, analyze_traces
+from .supervisor.monitor import TraceStore, build_boot_trace
+
+
+DEFAULT_ENTRYPOINTS = ("src/index.ts", "src/index.js", "index.ts", "index.js")
+DEFAULT_MODAL_IMAGE = "invoke/claude-agent-sdk:latest"
+
+
+@dataclass
+class DeployPlan:
+    """A concrete deployment plan for one agent project."""
+
+    project_root: str
+    app_name: str
+    entrypoint: str
+    modal_volume: str
+    modal_image: str = DEFAULT_MODAL_IMAGE
+    env: dict[str, str] = field(default_factory=dict)
+    endpoint_name: str = "invoke"
+    tracing_enabled: bool = True
+    persistence: dict[str, str] = field(default_factory=dict)
+    robustness: dict[str, bool] = field(default_factory=dict)
+
+
+@dataclass
+class DeployResult:
+    """Result returned by a deploy attempt or dry run."""
+
+    success: bool
+    plan: DeployPlan
+    deployment_id: str
+    status: str
+    message: str
+    modal_app_name: str | None = None
+    endpoint_url: str | None = None
+    dashboard_url: str | None = None
+    trace_path: str | None = None
+    modal_source_path: str | None = None
+    onyx_suggestions: list[OnyxSuggestion] = field(default_factory=list)
+
+
+def slugify(value: str) -> str:
+    cleaned = "".join(ch.lower() if ch.isalnum() else "-" for ch in value)
+    return "-".join(part for part in cleaned.split("-") if part) or "invoke-agent"
+
+
+def now_iso() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat()
+
+
+def load_project_config(project_root: Path) -> dict[str, Any]:
+    for name in ("invoke.json", "agent.json", "package.json"):
+        path = project_root / name
+        if path.exists():
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"Invalid JSON in {path}: {exc}") from exc
+            if isinstance(data, dict):
+                return data
+    return {}
+
+
+def infer_entrypoint(project_root: Path, config: dict[str, Any]) -> str:
+    configured = config.get("entrypoint") or config.get("main")
+    candidates = (str(configured),) if configured else DEFAULT_ENTRYPOINTS
+    for candidate in candidates:
+        if candidate and (project_root / candidate).exists():
+            return candidate
+    raise FileNotFoundError(
+        "Could not find an agent entrypoint. Expected one of: "
+        + ", ".join(DEFAULT_ENTRYPOINTS)
+        + ". You can also set `entrypoint` in invoke.json."
+    )
+
+
+def build_deploy_plan(project_path: str | Path, *, app_name: str | None = None) -> DeployPlan:
+    project_root = Path(project_path).expanduser().resolve()
+    if not project_root.exists() or not project_root.is_dir():
+        raise FileNotFoundError(f"Agent project does not exist: {project_root}")
+
+    config = load_project_config(project_root)
+    inferred_name = app_name or config.get("name") or project_root.name
+    slug = slugify(str(inferred_name))
+    entrypoint = infer_entrypoint(project_root, config)
+
+    env_keys = [
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+        "INVOKE_API_KEY",
+        "INVOKE_BASE_URL",
+    ]
+    env = {key: os.environ[key] for key in env_keys if os.environ.get(key)}
+
+    return DeployPlan(
+        project_root=str(project_root),
+        app_name=slug,
+        entrypoint=entrypoint,
+        modal_volume=f"{slug}-state",
+        env=env,
+        persistence={
+            "kind": "modal_volume",
+            "mount_path": "/state",
+            "trace_path": "/state/traces.jsonl",
+            "checkpoint_path": "/state/checkpoints.jsonl",
+        },
+        robustness={
+            "schema_checks": True,
+            "policy_checks": True,
+            "state_reconciliation": True,
+            "freeze_thaw_hitl": True,
+            "structured_tracing": True,
+        },
+    )
+
+
+def write_local_deploy_record(result: DeployResult) -> Path:
+    root = Path(result.plan.project_root)
+    state_dir = root / ".invoke"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    path = state_dir / "deployment.json"
+    path.write_text(json.dumps(asdict(result), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def copy_template(destination: str | Path, *, force: bool = False) -> Path:
+    """Scaffold a Claude Agent SDK starter project."""
+
+    destination = Path(destination).expanduser().resolve()
+    template_root = Path(__file__).with_name("templates") / "claude-agent-sdk"
+    if destination.exists() and any(destination.iterdir()) and not force:
+        raise FileExistsError(f"{destination} is not empty. Pass force=True to overwrite template files.")
+    destination.mkdir(parents=True, exist_ok=True)
+    for source in template_root.rglob("*"):
+        target = destination / source.relative_to(template_root)
+        if source.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if target.exists() and not force:
+            continue
+        shutil.copyfile(source, target)
+    return destination
+
+
+def deploy_claude_agent(
+    project_path: str | Path,
+    *,
+    app_name: str | None = None,
+    dry_run: bool = False,
+    run_onyx: bool = True,
+) -> DeployResult:
+    """Build and optionally deploy a Claude Agent SDK project to Modal."""
+
+    plan = build_deploy_plan(project_path, app_name=app_name)
+    deployment_id = "dep_" + dt.datetime.now(dt.timezone.utc).strftime("%Y%m%d%H%M%S")
+
+    trace_store = TraceStore(Path(plan.project_root) / ".invoke" / "traces.jsonl")
+    boot_trace = build_boot_trace(plan.app_name, plan.entrypoint, plan.robustness)
+    trace_store.append(boot_trace)
+
+    suggestions = analyze_traces(trace_store.recent(limit=100)) if run_onyx else []
+
+    from .sandbox import write_modal_source
+
+    modal_source_path = write_modal_source(plan)
+    dashboard_url = f"https://modal.com/apps/{plan.app_name}"
+
+    if dry_run:
+        result = DeployResult(
+            success=True,
+            plan=plan,
+            deployment_id=deployment_id,
+            status="planned",
+            message="Deployment plan generated. Modal deploy was not executed.",
+            dashboard_url=dashboard_url,
+            trace_path=str(trace_store.path),
+            modal_source_path=str(modal_source_path),
+            onyx_suggestions=suggestions,
+        )
+        write_local_deploy_record(result)
+        return result
+
+    from .sandbox import deploy_modal_app
+
+    modal_result = deploy_modal_app(plan)
+    result = DeployResult(
+        success=True,
+        plan=plan,
+        deployment_id=deployment_id,
+        status="deployed",
+        message="Agent deployed to Modal with Invoke tracing and persistence enabled.",
+        modal_app_name=modal_result.get("app_name", plan.app_name),
+        endpoint_url=modal_result.get("endpoint_url"),
+        dashboard_url=modal_result.get("dashboard_url", dashboard_url),
+        trace_path=str(trace_store.path),
+        modal_source_path=str(modal_source_path),
+        onyx_suggestions=suggestions,
+    )
+    write_local_deploy_record(result)
+    return result
+
+
+def main() -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Deploy a Claude Agent SDK project with Invoke.")
+    parser.add_argument("path", help="Agent project path.")
+    parser.add_argument("--app-name")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--template", action="store_true", help="Scaffold a starter project at path.")
+    args = parser.parse_args()
+
+    if args.template:
+        path = copy_template(args.path)
+        print(f"Created Claude Agent SDK template at {path}")
+        return 0
+
+    result = deploy_claude_agent(args.path, app_name=args.app_name, dry_run=args.dry_run)
+    print(json.dumps(asdict(result), indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/invoke/onyx/__init__.py

@@ -0,0 +1,5 @@
+"""Onyx Lite trace analyzer."""
+
+from .analyzer import OnyxSuggestion, analyze_traces
+
+__all__ = ["OnyxSuggestion", "analyze_traces"]

package/invoke/onyx/analyzer.py

@@ -0,0 +1,75 @@
+"""Onyx Lite: trace analysis and concrete repair suggestions."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class OnyxSuggestion:
+    title: str
+    severity: str
+    reason: str
+    apply: dict[str, Any] = field(default_factory=dict)
+
+
+def _flatten_events(trace: dict[str, Any]) -> list[dict[str, Any]]:
+    events = trace.get("events") or trace.get("trace") or []
+    if isinstance(events, list):
+        return [event for event in events if isinstance(event, dict)]
+    return []
+
+
+def analyze_traces(traces: list[dict[str, Any]]) -> list[OnyxSuggestion]:
+    """Detect repeated failures and emit safe, concrete fixes."""
+
+    if not traces:
+        return []
+
+    outcomes = Counter(str(trace.get("final_outcome") or trace.get("status") or "unknown") for trace in traces)
+    steps = Counter(event.get("step") for trace in traces for event in _flatten_events(trace) if event.get("step"))
+    suggestions: list[OnyxSuggestion] = []
+
+    if outcomes.get("timeout") or steps.get("tool_timeout"):
+        suggestions.append(
+            OnyxSuggestion(
+                title="Add reconciliation before retry",
+                severity="high",
+                reason="Recent traces include timeout patterns where the side effect may have succeeded.",
+                apply={"retry_strategy": "reconcile_before_retry", "unknown_effect": True},
+            )
+        )
+
+    if outcomes.get("idempotent_replay") or steps.get("duplicate_retry_detected"):
+        suggestions.append(
+            OnyxSuggestion(
+                title="Require idempotency keys for this action",
+                severity="medium",
+                reason="Duplicate retry patterns were detected in recent executions.",
+                apply={"idempotency": {"mode": "required", "key_fields": ["customer_id", "amount", "action"]}},
+            )
+        )
+
+    if outcomes.get("blocked_by_policy") or steps.get("policy_evaluated"):
+        suggestions.append(
+            OnyxSuggestion(
+                title="Move policy warning into preflight",
+                severity="medium",
+                reason="Policy blocked work after planning. Warn the agent before it attempts the action.",
+                apply={"preflight": {"policy_preview": True, "risk_threshold": "medium"}},
+            )
+        )
+
+    if not suggestions:
+        suggestions.append(
+            OnyxSuggestion(
+                title="No repeated failure pattern detected",
+                severity="info",
+                reason="Recent traces do not show recurring timeout, duplicate retry, or policy-block patterns.",
+                apply={},
+            )
+        )
+
+    return suggestions

package/invoke/sandbox.py

@@ -0,0 +1,388 @@
+"""Modal sandbox generation for hosted Invoke agents."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import textwrap
+from pathlib import Path
+from typing import Any
+
+from .deploy import DeployPlan
+
+
+ENDPOINT_RE = re.compile(r"https://[^\s\"']+modal\.run[^\s\"']*")
+
+
+def _require_modal_cli() -> None:
+    if shutil.which("modal"):
+        return
+    raise RuntimeError(
+        "Modal CLI is required for `invoke deploy` agent deployments. "
+        "Install and authenticate it with `pip install modal` and `modal setup`, "
+        "or run `invoke deploy --dry-run` to inspect the generated deployment first."
+    )
+
+
+def _remote_entrypoint_command(entrypoint: str) -> str:
+    quoted = json.dumps(entrypoint)
+    return textwrap.dedent(
+        f"""\
+        def agent_command(prompt):
+            entrypoint = {quoted}
+            source = Path("/workspace") / entrypoint
+            if entrypoint.endswith(".ts"):
+                compiled = Path("/workspace/dist") / Path(entrypoint).with_suffix(".js").name
+                if compiled.exists():
+                    return ["node", str(compiled), prompt]
+                return ["npx", "tsx", str(source), prompt]
+            return ["node", str(source), prompt]
+        """
+    )
+
+
+def modal_source(plan: DeployPlan) -> str:
+    """Build the deployable Modal source file for one agent project."""
+
+    app_name = json.dumps(plan.app_name)
+    volume_name = json.dumps(plan.modal_volume)
+    project_root = json.dumps(plan.project_root)
+    env = json.dumps(plan.env, sort_keys=True)
+    endpoint_name = json.dumps(plan.endpoint_name)
+    agent_command_source = _remote_entrypoint_command(plan.entrypoint).rstrip()
+
+    template = textwrap.dedent(
+        f"""\
+        # Generated by Invoke. Do not edit by hand; rerun `invoke deploy`.
+        from __future__ import annotations
+
+        import json
+        import os
+        import subprocess
+        import time
+        import uuid
+        from pathlib import Path
+        from typing import Any
+
+        import modal
+        from fastapi import Request
+
+
+        APP_NAME = {app_name}
+        VOLUME_NAME = {volume_name}
+        PROJECT_ROOT = {project_root}
+        INVOKE_ENV = {env}
+
+        app = modal.App(APP_NAME)
+        volume = modal.Volume.from_name(VOLUME_NAME, create_if_missing=True)
+
+        image = (
+            modal.Image.debian_slim(python_version="3.11")
+            .apt_install("nodejs", "npm")
+            .pip_install("fastapi[standard]")
+            .add_local_dir(
+                PROJECT_ROOT,
+                remote_path="/workspace",
+                copy=True,
+                ignore=[
+                    ".git",
+                    ".invoke",
+                    "node_modules",
+                    "dist",
+                    ".next",
+                    "__pycache__",
+                    "*.tgz",
+                ],
+            )
+            .run_commands(
+                "cd /workspace && if [ -f package-lock.json ]; then npm ci; elif [ -f package.json ]; then npm install; fi",
+                "cd /workspace && if [ -f package.json ]; then npm run build --if-present; fi",
+            )
+            .env(INVOKE_ENV)
+        )
+
+
+        def utc_ms():
+            return int(time.time() * 1000)
+
+
+        def append_jsonl(path, payload):
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with path.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(payload, sort_keys=True) + "\\n")
+
+
+        def read_jsonl(path):
+            if not path.exists():
+                return []
+            rows = []
+            for line in path.read_text(encoding="utf-8").splitlines():
+                try:
+                    rows.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+            return rows
+
+
+        def evaluate_policy(action, params):
+            lowered = str(action).lower()
+            sql = str(params.get("sql", "")).lower() if isinstance(params, dict) else ""
+            if action == "database.execute" or "disable row level security" in sql or "drop table" in sql:
+                return {{
+                    "effect": "block",
+                    "risk": "high",
+                    "reason": "Direct database execution can bypass application policy or row-level security.",
+                    "guardrails": ["policy_block", "sandbox_required"],
+                }}
+            if any(word in lowered for word in ("delete", "refund", "charge", "transfer")):
+                return {{
+                    "effect": "require_approval",
+                    "risk": "high",
+                    "reason": "Financial or destructive action requires approval and reconciliation.",
+                    "guardrails": ["approval", "idempotency_key", "state_reconciliation"],
+                }}
+            return {{
+                "effect": "allow",
+                "risk": "low",
+                "reason": "No blocking policy matched.",
+                "guardrails": ["trace"],
+            }}
+
+
+        def reconcile_state(expected, live):
+            drift = []
+            if isinstance(expected, dict) and isinstance(live, dict):
+                for key, expected_value in expected.items():
+                    if live.get(key) != expected_value:
+                        drift.append({{"key": key, "expected": expected_value, "live": live.get(key)}})
+            return {{"status": "changed" if drift else "valid", "drift": drift, "checked_at_ms": utc_ms()}}
+
+
+        def extract_action(payload):
+            raw = payload.get("action") or {{}}
+            if isinstance(raw, str):
+                return raw, payload.get("params") or {{}}
+            if isinstance(raw, dict):
+                return raw.get("action") or raw.get("name") or "agent.run", raw.get("params") or {{}}
+            return "agent.run", {{}}
+
+
+        def checkpoint_path():
+            return Path("/state/checkpoints.jsonl")
+
+
+        def trace_path():
+            return Path("/state/traces.jsonl")
+
+
+        def freeze_execution(execution_id, action, params, context):
+            checkpoint = {{
+                "checkpoint_id": "freeze_" + uuid.uuid4().hex[:12],
+                "execution_id": execution_id,
+                "action": action,
+                "params": params,
+                "context_snapshot": context,
+                "created_at_ms": utc_ms(),
+            }}
+            append_jsonl(checkpoint_path(), checkpoint)
+            return checkpoint
+
+
+        def find_checkpoint(checkpoint_id):
+            for checkpoint in reversed(read_jsonl(checkpoint_path())):
+                if checkpoint.get("checkpoint_id") == checkpoint_id:
+                    return checkpoint
+            return None
+
+
+        __AGENT_COMMAND_SOURCE__
+
+
+        @app.function(image=image, volumes={{"/state": volume}}, timeout=60 * 20)
+        @modal.fastapi_endpoint(method="POST", label={endpoint_name})
+        async def invoke(request: Request):
+            started = utc_ms()
+            payload = await request.json()
+            execution_id = payload.get("execution_id") or "exec_" + uuid.uuid4().hex[:12]
+            prompt = payload.get("prompt") or payload.get("input") or ""
+            agent_id = payload.get("agent_id") or APP_NAME
+            action, params = extract_action(payload)
+            events = []
+
+            def event(step, status, detail=None):
+                item = {{"step": step, "status": status, "timestamp_ms": utc_ms(), "detail": detail or {{}}}}
+                events.append(item)
+                return item
+
+            event("request_received", "ok", {{"agent_id": agent_id, "action": action}})
+
+            if not isinstance(params, dict):
+                event("schema_checked", "failed", {{"reason": "params must be an object"}})
+                trace = {{
+                    "execution_id": execution_id,
+                    "agent_id": agent_id,
+                    "action": action,
+                    "status": "blocked",
+                    "risk": "medium",
+                    "final_outcome": "blocked_by_schema",
+                    "events": events,
+                    "latency_ms": utc_ms() - started,
+                }}
+                append_jsonl(trace_path(), trace)
+                return {{"success": False, "execution": trace, "error": "params must be an object"}}
+            event("schema_checked", "ok")
+
+            if payload.get("resume_checkpoint_id"):
+                checkpoint = find_checkpoint(payload["resume_checkpoint_id"])
+                if not checkpoint:
+                    event("checkpoint_loaded", "missing", {{"checkpoint_id": payload["resume_checkpoint_id"]}})
+                    return {{"success": False, "execution_id": execution_id, "error": "checkpoint not found", "events": events}}
+                event("checkpoint_loaded", "ok", {{"checkpoint_id": checkpoint["checkpoint_id"]}})
+                revalidation = reconcile_state(checkpoint.get("context_snapshot") or {{}}, payload.get("live_context") or {{}})
+                event("state_revalidated", revalidation["status"], revalidation)
+                if revalidation["status"] == "changed":
+                    trace = {{
+                        "execution_id": execution_id,
+                        "agent_id": agent_id,
+                        "action": action,
+                        "status": "requeued",
+                        "risk": "high",
+                        "final_outcome": "requeued_due_to_state_drift",
+                        "events": events,
+                        "latency_ms": utc_ms() - started,
+                    }}
+                    append_jsonl(trace_path(), trace)
+                    return {{"success": True, "status": "requeued", "execution": trace}}
+
+            policy = evaluate_policy(action, params)
+            event("policy_evaluated", "ok", policy)
+            if policy["effect"] == "block":
+                trace = {{
+                    "execution_id": execution_id,
+                    "agent_id": agent_id,
+                    "action": action,
+                    "status": "blocked",
+                    "risk": policy["risk"],
+                    "policy": policy,
+                    "final_outcome": "blocked_by_policy",
+                    "events": events,
+                    "latency_ms": utc_ms() - started,
+                }}
+                append_jsonl(trace_path(), trace)
+                return {{"success": True, "status": "blocked", "execution": trace, "certificate_returned": True}}
+
+            if policy["effect"] == "require_approval" and not payload.get("approved"):
+                checkpoint = freeze_execution(
+                    execution_id,
+                    action,
+                    params,
+                    payload.get("context_snapshot") or payload.get("expected_state") or {{}},
+                )
+                event("execution_frozen", "pending_approval", {{"checkpoint_id": checkpoint["checkpoint_id"]}})
+                trace = {{
+                    "execution_id": execution_id,
+                    "agent_id": agent_id,
+                    "action": action,
+                    "status": "pending_approval",
+                    "risk": policy["risk"],
+                    "policy": policy,
+                    "checkpoint": checkpoint,
+                    "final_outcome": "frozen_for_human_review",
+                    "events": events,
+                    "latency_ms": utc_ms() - started,
+                }}
+                append_jsonl(trace_path(), trace)
+                return {{"success": True, "status": "pending_approval", "execution": trace, "certificate_returned": True}}
+
+            if payload.get("expected_state") is not None or payload.get("live_state") is not None:
+                reconciliation = reconcile_state(payload.get("expected_state") or {{}}, payload.get("live_state") or {{}})
+                event("state_reconciled", reconciliation["status"], reconciliation)
+                if reconciliation["status"] == "changed":
+                    trace = {{
+                        "execution_id": execution_id,
+                        "agent_id": agent_id,
+                        "action": action,
+                        "status": "blocked",
+                        "risk": "high",
+                        "policy": policy,
+                        "reconciliation": reconciliation,
+                        "final_outcome": "blocked_due_to_state_drift",
+                        "events": events,
+                        "latency_ms": utc_ms() - started,
+                    }}
+                    append_jsonl(trace_path(), trace)
+                    return {{"success": True, "status": "blocked", "execution": trace, "certificate_returned": True}}
+
+            event("agent_execution_started", "ok")
+            completed = subprocess.run(
+                agent_command(str(prompt)),
+                cwd="/workspace",
+                text=True,
+                capture_output=True,
+                timeout=int(payload.get("timeout_seconds") or 60 * 15),
+                check=False,
+            )
+            status = "succeeded" if completed.returncode == 0 else "failed"
+            event("agent_execution_completed", status, {{"returncode": completed.returncode}})
+            trace = {{
+                "execution_id": execution_id,
+                "agent_id": agent_id,
+                "action": action,
+                "status": status,
+                "risk": policy["risk"],
+                "policy": policy,
+                "final_outcome": status,
+                "events": events,
+                "latency_ms": utc_ms() - started,
+                "stdout": completed.stdout[-8000:],
+                "stderr": completed.stderr[-8000:],
+                "certificate_returned": True,
+            }}
+            append_jsonl(trace_path(), trace)
+            return {{"success": completed.returncode == 0, "execution": trace, "certificate_returned": True}}
+        """
+    )
+    return template.replace("__AGENT_COMMAND_SOURCE__", agent_command_source)
+
+
+def write_modal_source(plan: DeployPlan) -> Path:
+    state_dir = Path(plan.project_root) / ".invoke"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    path = state_dir / "modal_app.py"
+    path.write_text(modal_source(plan), encoding="utf-8")
+    return path
+
+
+def _parse_endpoint(output: str) -> str | None:
+    match = ENDPOINT_RE.search(output)
+    return match.group(0).rstrip(".,)")
+
+
+def deploy_modal_app(plan: DeployPlan) -> dict[str, Any]:
+    """Deploy the generated Modal app and return endpoint metadata."""
+
+    _require_modal_cli()
+    source_path = write_modal_source(plan)
+    completed = subprocess.run(
+        ["modal", "deploy", str(source_path)],
+        cwd=plan.project_root,
+        text=True,
+        capture_output=True,
+        timeout=60 * 10,
+        check=False,
+    )
+    output = (completed.stdout or "") + "\n" + (completed.stderr or "")
+    if completed.returncode != 0:
+        raise RuntimeError(f"Modal deploy failed with exit code {completed.returncode}:\n{output.strip()}")
+
+    endpoint_url = _parse_endpoint(output)
+    return {
+        "app_name": plan.app_name,
+        "volume": plan.modal_volume,
+        "endpoint_url": endpoint_url,
+        "dashboard_url": f"https://modal.com/apps/{plan.app_name}",
+        "source_path": str(source_path),
+        "deploy_output": output.strip(),
+    }

package/invoke/supervisor/__init__.py

@@ -0,0 +1,23 @@
+"""Supervision primitives for Invoke-hosted agents."""
+
+from .monitor import (
+    Checkpoint,
+    ExecutionTrace,
+    PolicyDecision,
+    TraceEvent,
+    TraceStore,
+    build_boot_trace,
+    evaluate_policy,
+    reconcile_state,
+)
+
+__all__ = [
+    "Checkpoint",
+    "ExecutionTrace",
+    "PolicyDecision",
+    "TraceEvent",
+    "TraceStore",
+    "build_boot_trace",
+    "evaluate_policy",
+    "reconcile_state",
+]

package/invoke/supervisor/monitor.py

@@ -0,0 +1,149 @@
+"""Structured tracing, policy checks, and freeze/thaw checkpoints."""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import uuid
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+def utc_now() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat()
+
+
+@dataclass
+class TraceEvent:
+    step: str
+    status: str
+    detail: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=utc_now)
+
+
+@dataclass
+class ExecutionTrace:
+    execution_id: str
+    agent_id: str
+    action: str
+    status: str
+    risk: str
+    events: list[TraceEvent] = field(default_factory=list)
+    final_outcome: str | None = None
+    created_at: str = field(default_factory=utc_now)
+
+
+@dataclass
+class PolicyDecision:
+    effect: str
+    risk: str
+    reason: str
+    requires_approval: bool = False
+    guardrails: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Checkpoint:
+    checkpoint_id: str
+    execution_id: str
+    action: str
+    params: dict[str, Any]
+    context_snapshot: dict[str, Any]
+    created_at: str = field(default_factory=utc_now)
+
+
+class TraceStore:
+    """Append-only JSONL trace store."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def append(self, trace: ExecutionTrace | dict[str, Any]) -> None:
+        payload = asdict(trace) if hasattr(trace, "__dataclass_fields__") else trace
+        with self.path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(payload, sort_keys=True) + "\n")
+
+    def recent(self, *, limit: int = 50) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        lines = self.path.read_text(encoding="utf-8").splitlines()[-limit:]
+        traces: list[dict[str, Any]] = []
+        for line in lines:
+            try:
+                traces.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return traces
+
+
+def evaluate_policy(action: str, params: dict[str, Any]) -> PolicyDecision:
+    lowered = action.lower()
+    sql = str(params.get("sql", "")).lower()
+    if action == "database.execute" or "disable row level security" in sql or "drop table" in sql:
+        return PolicyDecision(
+            effect="block",
+            risk="high",
+            reason="Direct database execution can bypass application policy or row-level security.",
+            guardrails=["policy_block", "sandbox_required"],
+        )
+    if any(word in lowered for word in ("delete", "refund", "charge", "transfer")):
+        return PolicyDecision(
+            effect="require_approval",
+            risk="high",
+            reason="Financial or destructive action requires approval and reconciliation.",
+            requires_approval=True,
+            guardrails=["approval", "idempotency_key", "state_reconciliation"],
+        )
+    return PolicyDecision(effect="allow", risk="low", reason="No blocking policy matched.", guardrails=["trace"])
+
+
+def reconcile_state(expected: dict[str, Any], live: dict[str, Any]) -> dict[str, Any]:
+    drift = []
+    for key, expected_value in expected.items():
+        if live.get(key) != expected_value:
+            drift.append({"key": key, "expected": expected_value, "live": live.get(key)})
+    return {
+        "status": "changed" if drift else "valid",
+        "drift": drift,
+        "checked_at": utc_now(),
+    }
+
+
+def freeze_execution(execution_id: str, action: str, params: dict[str, Any], context: dict[str, Any]) -> Checkpoint:
+    return Checkpoint(
+        checkpoint_id="freeze_" + uuid.uuid4().hex[:12],
+        execution_id=execution_id,
+        action=action,
+        params=params,
+        context_snapshot=context,
+    )
+
+
+def thaw_checkpoint(checkpoint: Checkpoint, live_context: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "checkpoint_id": checkpoint.checkpoint_id,
+        "execution_id": checkpoint.execution_id,
+        "revalidation": reconcile_state(checkpoint.context_snapshot, live_context),
+        "thawed_at": utc_now(),
+    }
+
+
+def build_boot_trace(app_name: str, entrypoint: str, robustness: dict[str, bool]) -> ExecutionTrace:
+    trace = ExecutionTrace(
+        execution_id="exec_" + uuid.uuid4().hex[:12],
+        agent_id=app_name,
+        action="invoke.deploy",
+        status="planned",
+        risk="low",
+        final_outcome="deployment_plan_recorded",
+    )
+    trace.events.extend(
+        [
+            TraceEvent("project_loaded", "ok", {"entrypoint": entrypoint}),
+            TraceEvent("persistence_selected", "ok", {"kind": "modal_volume"}),
+            TraceEvent("robustness_layer_enabled", "ok", robustness),
+        ]
+    )
+    return trace

package/invoke/templates/claude-agent-sdk/invoke.json

@@ -0,0 +1,10 @@
+{
+  "name": "my-claude-agent",
+  "entrypoint": "src/index.ts",
+  "runtime": "node",
+  "tools": [],
+  "policy": {
+    "approval_required_for": ["charge", "refund", "delete", "database.execute"],
+    "block": ["database.execute"]
+  }
+}

package/invoke/templates/claude-agent-sdk/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "invoke-claude-agent",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "latest"
+  },
+  "devDependencies": {
+    "tsx": "latest",
+    "typescript": "latest"
+  }
+}

package/invoke/templates/claude-agent-sdk/src/index.ts

@@ -0,0 +1,14 @@
+import { query } from "@anthropic-ai/claude-agent-sdk"
+
+const prompt = process.argv.slice(2).join(" ") || "Summarize what this agent can do."
+
+for await (const message of query({
+  prompt,
+  options: {
+    allowedTools: [],
+  },
+})) {
+  if ("result" in message) {
+    console.log(message.result)
+  }
+}

package/invoke/templates/claude-agent-sdk/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invokehq/cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "CLI for Invoke, execution reliability infrastructure for AI agents.",
   "license": "Apache-2.0",
   "bin": {
@@ -10,6 +10,13 @@
   "files": [
     "agentify.py",
     "bin",
+    "invoke/*.py",
+    "invoke/onyx/*.py",
+    "invoke/supervisor/*.py",
+    "invoke/templates/claude-agent-sdk/invoke.json",
+    "invoke/templates/claude-agent-sdk/package.json",
+    "invoke/templates/claude-agent-sdk/src/index.ts",
+    "invoke/templates/claude-agent-sdk/tsconfig.json",
     "README.md",
     "pyproject.toml"
   ],

package/pyproject.toml

@@ -24,5 +24,9 @@ dev = ["build", "twine"]
 invoke = "agentify:main"
 agentify = "agentify:main"
 
-[tool.setuptools.py-modules]
-modules = ["agentify"]
+[tool.setuptools]
+py-modules = ["agentify"]
+packages = ["invoke", "invoke.onyx", "invoke.supervisor"]
+
+[tool.setuptools.package-data]
+invoke = ["templates/claude-agent-sdk/*", "templates/claude-agent-sdk/src/*"]