multiagentos 0.4.0__py3-none-any.whl

runtime/quota.py

@@ -0,0 +1,259 @@
+"""Persistent quota intelligence for VYRELON model routing."""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from core.contracts.ai import ModelSpec
+from core.contracts.quota import QuotaConfidence, QuotaDimension, QuotaSnapshot
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _parse_dt(value: object) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+class QuotaStore:
+    """Persist the latest quota snapshot per model without storing credentials."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def path_for(self, model_id: str) -> Path:
+        safe = "".join(c if c.isalnum() or c in "._-" else "_" for c in model_id)
+        return self.root / f"{safe}.json"
+
+    def save(self, snapshot: QuotaSnapshot) -> Path:
+        payload = {
+            "model_id": snapshot.model_id,
+            "provider_id": snapshot.provider_id,
+            "observed_at": snapshot.observed_at.isoformat(),
+            "scope": snapshot.scope,
+            "metadata": snapshot.metadata,
+            "dimensions": [
+                {
+                    "name": item.name,
+                    "limit": item.limit,
+                    "used": item.used,
+                    "remaining": item.remaining,
+                    "reset_at": item.reset_at.isoformat() if item.reset_at else None,
+                    "window_seconds": item.window_seconds,
+                    "confidence": item.confidence.value,
+                    "source": item.source,
+                }
+                for item in snapshot.dimensions
+            ],
+        }
+        path = self.path_for(snapshot.model_id)
+        path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+        return path
+
+    def load(self, model_id: str) -> QuotaSnapshot:
+        data = json.loads(self.path_for(model_id).read_text(encoding="utf-8"))
+        dimensions = tuple(
+            QuotaDimension(
+                name=item["name"],
+                limit=item.get("limit"),
+                used=item.get("used"),
+                remaining=item.get("remaining"),
+                reset_at=_parse_dt(item.get("reset_at")),
+                window_seconds=item.get("window_seconds"),
+                confidence=QuotaConfidence(item.get("confidence", "unknown")),
+                source=item.get("source", "unknown"),
+            )
+            for item in data.get("dimensions", ())
+        )
+        observed_at = _parse_dt(data.get("observed_at")) or _now()
+        return QuotaSnapshot(
+            model_id=data["model_id"],
+            provider_id=data["provider_id"],
+            observed_at=observed_at,
+            dimensions=dimensions,
+            scope=data.get("scope", "model"),
+            metadata=dict(data.get("metadata", {})),
+        )
+
+    def exists(self, model_id: str) -> bool:
+        return self.path_for(model_id).exists()
+
+    def list_model_ids(self) -> tuple[str, ...]:
+        return tuple(sorted(path.stem for path in self.root.glob("*.json")))
+
+
+    def merge(self, snapshot: QuotaSnapshot) -> QuotaSnapshot:
+        """Merge a newer snapshot while preserving stronger existing dimensions."""
+        if not self.exists(snapshot.model_id):
+            self.save(snapshot)
+            return snapshot
+        current = self.load(snapshot.model_id)
+        if current.provider_id != snapshot.provider_id:
+            raise ValueError(f"Quota provider mismatch for {snapshot.model_id}")
+        rank = {
+            QuotaConfidence.UNKNOWN: 0,
+            QuotaConfidence.OBSERVED: 1,
+            QuotaConfidence.ESTIMATED: 2,
+            QuotaConfidence.ACTUAL: 3,
+        }
+        merged = {item.name: item for item in current.dimensions}
+        for item in snapshot.dimensions:
+            existing = merged.get(item.name)
+            if existing is None or rank[item.confidence] >= rank[existing.confidence]:
+                merged[item.name] = item
+        combined = QuotaSnapshot(
+            model_id=snapshot.model_id,
+            provider_id=snapshot.provider_id,
+            observed_at=max(current.observed_at, snapshot.observed_at),
+            dimensions=tuple(merged.values()),
+            scope=snapshot.scope or current.scope,
+            metadata={**current.metadata, **snapshot.metadata},
+        )
+        self.save(combined)
+        return combined
+
+
+
+class QuotaIntelligence:
+    """Turn provider metadata and configured limits into normalized snapshots."""
+
+    def __init__(self, store: QuotaStore) -> None:
+        self.store = store
+
+    def observe_response(self, model: ModelSpec, metadata: dict[str, Any]) -> QuotaSnapshot:
+        dimensions: list[QuotaDimension] = []
+        raw_limits = model.metadata.get("quota_limits", {})
+        configured = raw_limits if isinstance(raw_limits, dict) else {}
+        raw_actual = metadata.get("rate_limits", {})
+        actual = raw_actual if isinstance(raw_actual, dict) else {}
+        usage = metadata.get("usage", {})
+        usage = usage if isinstance(usage, dict) else {}
+
+        for name, value in actual.items():
+            if not isinstance(value, dict):
+                continue
+            limit = _number(value.get("limit"))
+            remaining = _number(value.get("remaining"))
+            reset_at = _parse_dt(value.get("reset_at"))
+            reset_seconds = _number(value.get("reset_seconds"))
+            if reset_at is None and reset_seconds is not None:
+                reset_at = datetime.fromtimestamp(
+                    _now().timestamp() + float(reset_seconds), tz=timezone.utc
+                )
+            used = limit - remaining if limit is not None and remaining is not None else None
+            dimensions.append(
+                QuotaDimension(
+                    name=name,
+                    limit=limit,
+                    used=used,
+                    remaining=remaining,
+                    reset_at=reset_at,
+                    confidence=QuotaConfidence.ACTUAL,
+                    source=str(value.get("source", "provider")),
+                )
+            )
+
+        usage_map = {
+            "requests": 1,
+            "input_tokens": usage.get("input_tokens"),
+            "output_tokens": usage.get("output_tokens"),
+            "total_tokens": usage.get("total_tokens"),
+        }
+        for name, increment in usage_map.items():
+            if increment is None or any(item.name == name for item in dimensions):
+                continue
+            limit_spec = configured.get(name)
+            if not isinstance(limit_spec, dict):
+                dimensions.append(
+                    QuotaDimension(name=name, used=_number(increment), confidence=QuotaConfidence.OBSERVED, source="response_usage")
+                )
+                continue
+            limit = _number(limit_spec.get("limit"))
+            prior_used = 0
+            if self.store.exists(model.id):
+                previous = self.store.load(model.id).dimension(name)
+                prior_used = float(previous.used or 0) if previous else 0
+            used = prior_used + float(increment)
+            remaining = max(0, limit - used) if limit is not None else None
+            dimensions.append(
+                QuotaDimension(
+                    name=name,
+                    limit=limit,
+                    used=used,
+                    remaining=remaining,
+                    reset_at=_parse_dt(limit_spec.get("reset_at")),
+                    window_seconds=int(limit_spec["window_seconds"]) if limit_spec.get("window_seconds") else None,
+                    confidence=QuotaConfidence.ESTIMATED if limit is not None else QuotaConfidence.OBSERVED,
+                    source="configured_limit",
+                )
+            )
+
+        merged: dict[str, QuotaDimension] = {}
+        if self.store.exists(model.id):
+            for item in self.store.load(model.id).dimensions:
+                merged[item.name] = item
+        for item in dimensions:
+            merged[item.name] = item
+
+        snapshot = QuotaSnapshot(
+            model_id=model.id,
+            provider_id=model.provider_id,
+            observed_at=_now(),
+            dimensions=tuple(merged.values()),
+            scope=str(model.metadata.get("quota_scope", "model")),
+        )
+        return self.store.merge(snapshot)
+
+
+def _number(value: object) -> int | float | None:
+    if value is None:
+        return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return int(number) if number.is_integer() else number
+
+
+def quota_available(snapshot: QuotaSnapshot, threshold: float = 0.05) -> bool:
+    """Return whether any known limiting dimension has usable capacity."""
+    now = _now()
+    known = [
+        item for item in snapshot.dimensions
+        if item.remaining is not None
+        and not (item.reset_at is not None and item.reset_at <= now)
+    ]
+    if not known:
+        return True
+    return all(
+        float(item.remaining) > 0
+        and (
+            item.limit in (None, 0)
+            or float(item.remaining) / float(item.limit) > threshold
+        )
+        for item in known
+    )
+
+
+def quota_score(snapshot: QuotaSnapshot) -> float:
+    """Return a normalized 0..1 score for routing among known quotas."""
+    now = _now()
+    known = [
+        item
+        for item in snapshot.dimensions
+        if item.remaining is not None
+        and item.limit not in (None, 0)
+        and not (item.reset_at is not None and item.reset_at <= now)
+    ]
+    if not known:
+        return 0.5
+    return max(0.0, min(1.0, min(float(item.remaining) / float(item.limit) for item in known)))

runtime/repository.py

@@ -0,0 +1,103 @@
+"""Repository runtime combining Git, GitHub, checkpoints, recovery, and evidence."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from core.contracts.repository import RecoveryResult, RepositoryCheckpoint, RepositoryEvidence
+from runtime.git import GitRuntime
+from runtime.github import GitHubRuntime
+from runtime.policy import ExecutionPolicy
+
+
+class RepositoryRuntime:
+    def __init__(
+        self,
+        git: GitRuntime,
+        github: GitHubRuntime,
+        policy: ExecutionPolicy | None = None,
+    ) -> None:
+        self.policy = policy or ExecutionPolicy()
+        self.git = git
+        self.github = github
+
+    def checkpoint(self, project_root: Path, *, metadata: dict[str, object] | None = None) -> RepositoryCheckpoint:
+        checkpoint_id = f"cp-{uuid.uuid4().hex[:12]}"
+        marker = f"VYRELON checkpoint {checkpoint_id}"
+        initial_status = self.git.status(project_root.as_posix())
+        has_changes = bool(initial_status.stdout.splitlines()[1:])
+        stashed = False
+        if has_changes:
+            result = self.git.stash(project_root.as_posix(), "push", marker)
+            stashed = result.returncode == 0
+            if not stashed:
+                raise RuntimeError(result.stderr.strip() or "failed to create Git checkpoint")
+        status = self.git.status(project_root.as_posix())
+        diff = self.git.diff(project_root.as_posix())
+        checkpoint = RepositoryCheckpoint(
+            id=checkpoint_id,
+            project_root=str(project_root),
+            marker=marker,
+            status=status.stdout,
+            diff=diff.stdout,
+            created_at=datetime.now(timezone.utc).isoformat(),
+            metadata={**dict(metadata or {}), "stashed": stashed},
+        )
+        self._persist_checkpoint(project_root, checkpoint)
+        return checkpoint
+
+    def recover(self, project_root: Path, checkpoint: RepositoryCheckpoint) -> RecoveryResult:
+        if not bool(checkpoint.metadata.get("stashed", False)):
+            return RecoveryResult(checkpoint.id, True, "No local changes required recovery", "")
+        result = self.git.stash(project_root.as_posix(), "pop")
+        if result.returncode == 0:
+            return RecoveryResult(checkpoint.id, True, result.stdout, "")
+        return RecoveryResult(checkpoint.id, False, result.stdout, result.stderr)
+
+    def evidence(
+        self,
+        project_root: Path,
+        *,
+        repository: str | None = None,
+        ref: str | None = None,
+        validation: dict[str, object] | None = None,
+    ) -> RepositoryEvidence:
+        status = self.git.status(project_root.as_posix())
+        diff = self.git.diff(project_root.as_posix())
+        workflows = ()
+        if repository and ref:
+            workflows = tuple(self.github.gateway.list_workflows(repository, ref))
+        evidence = RepositoryEvidence(
+            checkpoint_id=self._latest_checkpoint_id(project_root),
+            git_status=status.stdout,
+            git_diff=diff.stdout,
+            workflows=workflows,
+            validation=validation,
+            metadata={"runtime": "vyrelon-repository"},
+        )
+        path = project_root / ".multiagentos" / "evidence" / "repository.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({
+            "checkpoint_id": evidence.checkpoint_id,
+            "git_status": evidence.git_status,
+            "git_diff": evidence.git_diff,
+            "workflows": [getattr(item, "__dict__", str(item)) for item in evidence.workflows],
+            "validation": evidence.validation,
+            "metadata": evidence.metadata,
+        }, indent=2, default=str) + "\n", encoding="utf-8")
+        return evidence
+
+    def _persist_checkpoint(self, project_root: Path, checkpoint: RepositoryCheckpoint) -> None:
+        path = project_root / ".multiagentos" / "checkpoints" / f"{checkpoint.id}.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(checkpoint.__dict__, indent=2) + "\n", encoding="utf-8")
+
+    def _latest_checkpoint_id(self, project_root: Path) -> str | None:
+        directory = project_root / ".multiagentos" / "checkpoints"
+        if not directory.exists():
+            return None
+        files = sorted(directory.glob("cp-*.json"), key=lambda item: item.stat().st_mtime, reverse=True)
+        return files[0].stem if files else None

runtime/repository_tools.py

@@ -0,0 +1,62 @@
+"""Repository and MCP bindings for the normalized ToolRuntime."""
+from __future__ import annotations
+from dataclasses import dataclass
+from core.contracts.mcp import MCPToolCall
+from core.contracts.vyrelon_runtime import ToolRequest, ToolSideEffect, ToolSpec
+from runtime.git import GitRuntime
+from runtime.mcp.client import MCPClient
+from runtime.tool_calling import ToolRuntime
+
+@dataclass
+class GitToolBindings:
+    project_root: str
+    runtime: ToolRuntime
+    git: GitRuntime | None = None
+
+    def __post_init__(self) -> None:
+        self.git = self.git or GitRuntime(policy=self.runtime.policy)
+        self._register()
+
+    def _register(self) -> None:
+        self.runtime.register(ToolSpec("git.status","Show Git working tree status.",ToolSideEffect.READ,input_schema={"type":"object"}),self._status)
+        self.runtime.register(ToolSpec("git.diff","Show Git diff.",ToolSideEffect.READ,input_schema={"type":"object"}),self._diff)
+        self.runtime.register(ToolSpec("git.log","Show recent Git commits.",ToolSideEffect.READ,input_schema={"type":"object"}),self._log)
+        self.runtime.register(ToolSpec("git.add","Stage Git paths.",ToolSideEffect.WRITE,frozenset({"git.write"}),{"type":"object"}),self._add)
+        self.runtime.register(ToolSpec("git.commit","Create a Git commit.",ToolSideEffect.WRITE,frozenset({"git.write"}),{"type":"object","required":["message"]}),self._commit)
+        self.runtime.register(ToolSpec("git.push","Push Git changes.",ToolSideEffect.NETWORK,frozenset({"git.write","network"}),{"type":"object"}),self._push)
+
+    def _result(self,result: object) -> object:
+        return {"returncode":result.returncode,"stdout":result.stdout,"stderr":result.stderr}
+
+    def _status(self,r: ToolRequest): return self._result(self.git.status(self.project_root))
+    def _diff(self,r: ToolRequest): return self._result(self.git.diff(self.project_root,staged=r.arguments.get("staged") is True,path=r.arguments.get("path") if isinstance(r.arguments.get("path"),str) else None))
+    def _log(self,r: ToolRequest): return self._result(self.git.log(self.project_root,int(r.arguments.get("count",10))))
+    def _add(self,r: ToolRequest): return self._result(self.git.add(self.project_root,list(r.arguments.get("paths",[])) or None))
+    def _commit(self,r: ToolRequest):
+        message=r.arguments.get("message")
+        if not isinstance(message,str) or not message.strip(): raise ValueError("message must be a non-empty string")
+        return self._result(self.git.commit(self.project_root,message,approved=r.metadata.get("approved") is True))
+    def _push(self,r: ToolRequest):
+        return self._result(self.git.push(self.project_root,str(r.arguments.get("remote","origin")),r.arguments.get("branch") if isinstance(r.arguments.get("branch"),str) else None,approved=r.metadata.get("approved") is True))
+
+@dataclass
+class MCPToolBindings:
+    runtime: ToolRuntime
+    client: MCPClient
+
+    def register_tools(self, tools: tuple[object,...] | None = None) -> tuple[str,...]:
+        available=tools if tools is not None else self.client.list_tools()
+        ids=[]
+        for tool in available:
+            qualified=f"mcp.{tool.server_id}.{tool.name}"
+            self.runtime.register(ToolSpec(qualified,tool.description or qualified,tool.side_effect,tool.permissions,tool.input_schema,{"source":"mcp","server_id":tool.server_id,"tool_name":tool.name}),self._handler(tool.server_id,tool.name))
+            ids.append(qualified)
+        return tuple(ids)
+
+    def _handler(self,server_id:str,tool_name:str):
+        def invoke(request:ToolRequest):
+            result=self.client.call_tool(MCPToolCall(server_id,tool_name,request.arguments,request.session_id))
+            if result.is_error:
+                raise RuntimeError(f"MCP tool error: {server_id}:{tool_name}")
+            return {"content":result.content,"raw":result.raw}
+        return invoke

runtime/status.py

@@ -0,0 +1,87 @@
+"""Project-level VYRELON installation and workflow status."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def project_status(project_root: Path) -> dict[str, object]:
+    """Return a read-only summary of installed components and durable state."""
+    root = project_root.expanduser().resolve()
+    target = root / ".multiagentos"
+    result: dict[str, object] = {
+        "project_root": str(root),
+        "initialized": target.is_dir(),
+        "components": [],
+        "profiles": [],
+        "execution": None,
+        "chat": None,
+        "agents": [],
+        "work_units": [],
+        "checkpoints": [],
+    }
+    if not target.is_dir():
+        return result
+
+    components_path = target / "components.json"
+    if components_path.exists():
+        data = json.loads(components_path.read_text(encoding="utf-8"))
+        result["components"] = list(data.get("components", []))
+
+    profile_path = target / "profile.json"
+    if profile_path.exists():
+        data = json.loads(profile_path.read_text(encoding="utf-8"))
+        result["profiles"] = list(data.get("profiles", []))
+
+    chat_path = target / "chat.json"
+    if chat_path.exists():
+        data = json.loads(chat_path.read_text(encoding="utf-8"))
+        result["chat"] = {
+            "agent_id": data.get("agent_id", ""),
+            "model": data.get("model"),
+        }
+
+    execution_path = target / "execution.json"
+    if execution_path.exists():
+        data = json.loads(execution_path.read_text(encoding="utf-8"))
+        result["execution"] = {
+            "runtime": data.get("runtime", ""),
+            "agent_id": data.get("agent_id", ""),
+            "model_id": data.get("model_id", ""),
+        }
+
+    agents_path = target / "agents.json"
+    if agents_path.exists():
+        data = json.loads(agents_path.read_text(encoding="utf-8"))
+        result["agents"] = [agent.get("id", "") for agent in data.get("agents", [])]
+
+    state_root = target / "state"
+    if state_root.is_dir():
+        for path in sorted(state_root.glob("*.json")):
+            data = json.loads(path.read_text(encoding="utf-8"))
+            result["work_units"].append(
+                {
+                    "id": data.get("id", path.stem),
+                    "objective": data.get("objective", ""),
+                    "status": data.get("status", ""),
+                }
+            )
+
+    checkpoint_root = target / "checkpoints"
+    if checkpoint_root.is_dir():
+        for path in sorted(checkpoint_root.glob("*.json")):
+            data = json.loads(path.read_text(encoding="utf-8"))
+            result["checkpoints"].append(
+                {
+                    "work_unit_id": data.get("work_unit_id", path.stem),
+                    "workflow": data.get("workflow", ""),
+                    "stage": data.get("stage", ""),
+                    "status": data.get("status", ""),
+                    "next_action": data.get("next_action"),
+                    "sequence": data.get("sequence", 0),
+                    "resumable": bool(data.get("resumable", True)),
+                }
+            )
+
+    return result

runtime/tool_calling.py

@@ -0,0 +1,134 @@
+"""Provider-neutral AI tool-calling runtime."""
+from __future__ import annotations
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Protocol
+from core.contracts.ai import ModelSpec
+from core.contracts.model_runtime import ModelAdapter, ModelRequest, ModelResponse
+from core.contracts.vyrelon_runtime import RuntimeEvent, RuntimeEventKind, SessionSpec, ToolRequest, ToolResult, ToolSideEffect, ToolSpec
+from runtime.policy import ExecutionPolicy
+
+class ToolExecutionError(RuntimeError):
+    pass
+
+class ToolHandler(Protocol):
+    def __call__(self, request: ToolRequest) -> object: ...
+
+@dataclass(frozen=True)
+class RegisteredTool:
+    spec: ToolSpec
+    handler: ToolHandler
+
+class ToolRuntime:
+    """Central registry and policy boundary for normalized tool calls."""
+    def __init__(self, policy: ExecutionPolicy | None = None) -> None:
+        self.policy = policy or ExecutionPolicy()
+        self._tools: dict[str, RegisteredTool] = {}
+
+    def register(self, spec: ToolSpec, handler: ToolHandler) -> None:
+        if not spec.id.strip():
+            raise ValueError("tool id must not be empty")
+        if spec.id in self._tools:
+            raise ValueError(f"tool already registered: {spec.id}")
+        self._tools[spec.id] = RegisteredTool(spec, handler)
+
+    def specs(self) -> tuple[ToolSpec, ...]:
+        return tuple(item.spec for item in self._tools.values())
+
+    def unregister(self, tool_id: str) -> None:
+        """Remove a registered tool from the current scoped runtime."""
+        self._tools.pop(tool_id, None)
+
+    def execute(self, request: ToolRequest, *, granted_permissions: frozenset[str] = frozenset(), approved: bool = False) -> ToolResult:
+        item = self._tools.get(request.tool_id)
+        if item is None:
+            return ToolResult(request.tool_id, False, error=f"tool not registered: {request.tool_id}")
+        missing = item.spec.permissions - granted_permissions
+        if missing:
+            return ToolResult(item.spec.id, False, error=f"tool permission denied: missing={sorted(missing)}")
+        capability = {ToolSideEffect.READ: None, ToolSideEffect.WRITE: "filesystem.write", ToolSideEffect.EXECUTE: "process", ToolSideEffect.NETWORK: "network"}[item.spec.side_effect]
+        if capability and not self.policy.permits(capability):
+            return ToolResult(item.spec.id, False, error=f"tool capability is disabled: {capability}")
+        if capability and self.policy.requires_approval(capability) and not approved:
+            return ToolResult(item.spec.id, False, error=f"explicit approval required for: {capability}")
+        try:
+            output = item.handler(request)
+        except Exception as exc:
+            return ToolResult(item.spec.id, False, error=str(exc))
+        return ToolResult(item.spec.id, True, output=output, metadata={"side_effect": item.spec.side_effect.value})
+
+class ToolCallingAdapter(Protocol):
+    def generate_with_tools(self, model: ModelSpec, request: ModelRequest, tools: tuple[ToolSpec, ...]) -> ModelResponse: ...
+
+@dataclass(frozen=True)
+class ToolCallingExecution:
+    response: ModelResponse
+    model_id: str
+    rounds: int
+    tool_results: tuple[ToolResult, ...]
+
+class ToolCallingRuntime:
+    """Execute normalized model tool calls until the model returns a final response."""
+    def __init__(self, *, models: dict[str, ModelSpec], adapters: dict[str, ModelAdapter], tools: ToolRuntime, max_rounds: int = 8) -> None:
+        if max_rounds < 1:
+            raise ValueError("max_rounds must be at least 1")
+        self.models, self.adapters, self.tools, self.max_rounds = models, adapters, tools, max_rounds
+
+    def execute(self, request: ModelRequest, *, model_id: str, session: SessionSpec | None = None, work_unit_id: str | None = None, granted_permissions: frozenset[str] = frozenset(), approved: bool = False) -> ToolCallingExecution:
+        model = self.models[model_id]
+        adapter = self.adapters[model_id]
+        generate = getattr(adapter, "generate_with_tools", None)
+        if not callable(generate):
+            raise ToolExecutionError(f"model adapter does not support tool calling: {model_id}")
+        current, results = request, []
+        history: list[dict[str, object]] = []
+        for round_number in range(1, self.max_rounds + 1):
+            response = generate(model, current, self.tools.specs())
+            calls = self._normalize_calls(response.metadata.get("tool_calls", ()))
+            if not calls:
+                return ToolCallingExecution(response, model_id, round_number, tuple(results))
+            round_results = []
+            for call in calls:
+                result = self.tools.execute(
+                    ToolRequest(call["tool_id"], call["arguments"], session_id=session.id if session else None, work_unit_id=work_unit_id, metadata={"call_id": call["call_id"]}),
+                    granted_permissions=granted_permissions, approved=approved,
+                )
+                results.append(result)
+                round_results.append({"call_id": call["call_id"], "tool_id": result.tool_id, "ok": result.ok, "output": result.output, "error": result.error})
+            history.append({"tool_calls": calls, "tool_results": tuple(round_results)})
+            metadata = dict(current.metadata)
+            metadata["tool_results"] = tuple(round_results)
+            metadata["tool_history"] = tuple(history)
+            current = ModelRequest(prompt=current.prompt, system=current.system, metadata=metadata)
+        raise ToolExecutionError(f"tool calling exceeded maximum rounds: {self.max_rounds}")
+
+    def events(self, request: ModelRequest, *, model_id: str, session: SessionSpec | None = None, work_unit_id: str | None = None, granted_permissions: frozenset[str] = frozenset(), approved: bool = False) -> Iterator[RuntimeEvent]:
+        sequence = 0
+        def emit(kind: RuntimeEventKind, payload: object) -> RuntimeEvent:
+            nonlocal sequence
+            sequence += 1
+            return RuntimeEvent(kind=kind, session_id=session.id if session else None, work_unit_id=work_unit_id, payload=payload, sequence=sequence)
+        yield emit(RuntimeEventKind.REQUEST, {"model_id": model_id})
+        result = self.execute(request, model_id=model_id, session=session, work_unit_id=work_unit_id, granted_permissions=granted_permissions, approved=approved)
+        for item in result.tool_results:
+            yield emit(RuntimeEventKind.TOOL_CALL, {"tool_id": item.tool_id})
+            yield emit(RuntimeEventKind.TOOL_RESULT, item)
+        yield emit(RuntimeEventKind.MESSAGE, {"model_id": result.model_id, "text": result.response.text})
+        yield emit(RuntimeEventKind.COMPLETED, {"model_id": result.model_id, "rounds": result.rounds})
+
+    @staticmethod
+    def _normalize_calls(value: object) -> tuple[dict[str, object], ...]:
+        if not isinstance(value, (list, tuple)):
+            return ()
+        out = []
+        for i, item in enumerate(value):
+            if not isinstance(item, dict):
+                raise ToolExecutionError("tool call must be an object")
+            tool_id = item.get("tool_id", item.get("name"))
+            if not isinstance(tool_id, str) or not tool_id:
+                raise ToolExecutionError("tool call is missing tool_id")
+            args = item.get("arguments", {})
+            if not isinstance(args, dict):
+                raise ToolExecutionError(f"tool call arguments must be an object: {tool_id}")
+            out.append({"call_id": str(item.get("call_id", item.get("id", f"call-{i+1}"))), "tool_id": tool_id, "arguments": dict(args)})
+        return tuple(out)