ouro-agent 0.2.0__py3-none-any.whl

ouro/__init__.py

@@ -0,0 +1,5 @@
+"""OURO Agent runtime package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

ouro/application/__init__.py

@@ -0,0 +1,155 @@
+"""Application services that orchestrate OURO core runtime boundaries."""
+
+from ouro.application.agent_definitions import AgentDefinitionService
+from ouro.application.agent_models import (
+    AgentDefinitionCatalogView,
+    AgentDefinitionDetail,
+    AgentDefinitionView,
+    AgentHandleView,
+    AgentInteractionSummary,
+    AgentInteractionView,
+    AgentReadView,
+    AgentTreeEdge,
+    AgentTreeNode,
+    AgentTreeNotification,
+    AgentTreeSnapshot,
+    AgentWaitResultView,
+    SpawnAgentRequest,
+)
+from ouro.application.agent_tree import AgentTreeSubscription
+from ouro.application.agents import AgentService
+from ouro.application.configuration import ConfigurationFacade
+from ouro.application.configuration_models import (
+    ConfigurationOverview,
+    MCPConfigCatalogView,
+    MCPConnectionCheckView,
+    MCPServerConfigView,
+)
+from ouro.application.dto import ApplicationStartupReport
+from ouro.application.event_models import RuntimeEventCategory, RuntimeEventView
+from ouro.application.events import RuntimeEventRecorder, RuntimeEventSinkRegistration
+from ouro.application.models import ModelReasoningState
+from ouro.application.queued_inputs import QueuedUserInputView
+from ouro.application.resources import ResourceService
+from ouro.application.runtime import RuntimeService
+from ouro.application.runtime_configuration import (
+    RuntimeConfigurationResolver,
+    RuntimeConfigurationSnapshot,
+    RuntimeProviderOptions,
+)
+from ouro.application.session_models import (
+    ReplayFrame,
+    SessionBranchResult,
+    SessionCatalogEntry,
+    SessionCatalogQuery,
+    SessionCatalogResult,
+    SessionContextSnapshot,
+    SessionContextStatus,
+    SessionDetail,
+    SessionEventPage,
+    SessionExport,
+    SessionMessagePage,
+    SessionMutationResult,
+    SessionObservationSnapshot,
+    SessionReplay,
+    SessionSummary,
+    SessionTrashResult,
+    SessionView,
+)
+from ouro.application.sessions import SessionService, SessionTitleGenerator
+from ouro.application.supervisor import RuntimeSubscription, RuntimeSupervisor
+from ouro.application.supervisor_models import (
+    RUNTIME_TOOL_ARGUMENT_TAIL_MAX_CHARS,
+    HostInputReceipt,
+    RunHandle,
+    RuntimeActivity,
+    RuntimeActivitySnapshot,
+    RuntimeNotification,
+    RuntimeStatusSnapshot,
+    RuntimeToolCallActivity,
+    ShutdownPolicy,
+    SupervisorStartResult,
+)
+from ouro.application.usage import UsageService
+from ouro.core.results import RunResult
+from ouro.core.usage_queries import (
+    UsageAuditLog,
+    UsageEntryList,
+    UsageMutationResult,
+    UsageSummary,
+    UsageTotals,
+)
+
+__all__ = [
+    "AgentDefinitionCatalogView",
+    "AgentDefinitionDetail",
+    "AgentDefinitionService",
+    "AgentDefinitionView",
+    "AgentHandleView",
+    "AgentInteractionSummary",
+    "AgentInteractionView",
+    "AgentReadView",
+    "AgentService",
+    "AgentTreeEdge",
+    "AgentTreeNotification",
+    "AgentTreeNode",
+    "AgentTreeSnapshot",
+    "AgentTreeSubscription",
+    "AgentWaitResultView",
+    "ApplicationStartupReport",
+    "ConfigurationFacade",
+    "ConfigurationOverview",
+    "HostInputReceipt",
+    "MCPConfigCatalogView",
+    "MCPConnectionCheckView",
+    "MCPServerConfigView",
+    "ModelReasoningState",
+    "QueuedUserInputView",
+    "RUNTIME_TOOL_ARGUMENT_TAIL_MAX_CHARS",
+    "RunResult",
+    "RuntimeEventRecorder",
+    "RuntimeEventSinkRegistration",
+    "RuntimeEventCategory",
+    "RuntimeEventView",
+    "RuntimeService",
+    "RuntimeConfigurationResolver",
+    "RuntimeConfigurationSnapshot",
+    "RuntimeProviderOptions",
+    "RuntimeSupervisor",
+    "RuntimeSubscription",
+    "ResourceService",
+    "RunHandle",
+    "RuntimeNotification",
+    "RuntimeActivity",
+    "RuntimeActivitySnapshot",
+    "RuntimeStatusSnapshot",
+    "RuntimeToolCallActivity",
+    "ShutdownPolicy",
+    "SupervisorStartResult",
+    "UsageAuditLog",
+    "UsageEntryList",
+    "UsageMutationResult",
+    "UsageService",
+    "UsageSummary",
+    "UsageTotals",
+    "ReplayFrame",
+    "SessionBranchResult",
+    "SessionCatalogEntry",
+    "SessionService",
+    "SessionTitleGenerator",
+    "SessionCatalogQuery",
+    "SessionCatalogResult",
+    "SessionContextSnapshot",
+    "SessionContextStatus",
+    "SessionDetail",
+    "SessionEventPage",
+    "SessionExport",
+    "SessionMessagePage",
+    "SessionMutationResult",
+    "SessionObservationSnapshot",
+    "SessionReplay",
+    "SessionSummary",
+    "SessionTrashResult",
+    "SessionView",
+    "SpawnAgentRequest",
+]

ouro/application/agent_definitions.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ouro.application.agent_models import (
+    AgentDefinitionCatalogView,
+    AgentDefinitionDetail,
+    AgentDefinitionView,
+    AgentToolOptionView,
+)
+from ouro.config.agents import AgentDefinitionsConfigManager
+from ouro.config.providers import ProviderConfigManager
+from ouro.core.agents import (
+    AGENT_CONTROL_TOOL_NAMES,
+    AgentCatalogEntry,
+    AgentCatalogSnapshot,
+    AgentDefinition,
+    EffectiveToolRef,
+    ToolSelection,
+)
+from ouro.core.approvals import (
+    PermissionMode,
+    SessionApprovalMode,
+    configured_tool_permission,
+    resolve_tool_permission,
+)
+from ouro.core.errors import ConfigError
+from ouro.core.tools import tool_definition_contract_hash
+from ouro.tools import ToolDefinition, ToolRegistry
+
+GENERAL_AGENT_DEFINITION = AgentDefinition(
+    agent_id="general",
+    name="General",
+    description="A general-purpose subagent for a bounded delegated task.",
+    system_prompt=(
+        "Work independently on the delegated task. Use only the available tools and return "
+        "a concise result with evidence, verification, and unresolved questions."
+    ),
+    tool_selection=ToolSelection(mode="all"),
+    can_spawn=False,
+)
+
+
+class AgentDefinitionService:
+    """Resolve definitions and current tool capabilities for one decision."""
+
+    def __init__(self, config: AgentDefinitionsConfigManager) -> None:
+        self.config = config
+        self.providers = ProviderConfigManager(config.file.root)
+
+    def default_model_route(self) -> str:
+        return self.providers.require_default_route()
+
+    def list(self, *, tools: ToolRegistry) -> AgentDefinitionCatalogView:
+        config = self.config.snapshot()
+        entries = self._entries(tools)
+        return AgentDefinitionCatalogView(
+            revision=config.revision,
+            definitions=tuple(
+                self._view(
+                    entry,
+                    source=(
+                        "builtin"
+                        if entry.definition.agent_id == GENERAL_AGENT_DEFINITION.agent_id
+                        else "user"
+                    ),
+                )
+                for entry in entries
+            ),
+        )
+
+    def get(self, agent_id: str, *, tools: ToolRegistry) -> AgentDefinitionDetail:
+        entry = next(
+            (item for item in self._entries(tools) if item.definition.agent_id == agent_id),
+            None,
+        )
+        if entry is None:
+            raise ConfigError(f"agent definition not found: {agent_id}")
+        source = "builtin" if agent_id == GENERAL_AGENT_DEFINITION.agent_id else "user"
+        view = self._view(entry, source=source)
+        return AgentDefinitionDetail(
+            **view.model_dump(), system_prompt=entry.definition.system_prompt
+        )
+
+    def create(
+        self,
+        *,
+        agent_id: str,
+        name: str,
+        description: str,
+        system_prompt: str,
+        tool_selection: ToolSelection,
+        model: str | None = None,
+        tools: ToolRegistry,
+        expected_revision: int,
+    ) -> AgentDefinitionCatalogView:
+        self._require_known_selected_tools(tool_selection, tools)
+        definition = AgentDefinition(
+            agent_id=agent_id,
+            name=name,
+            description=description,
+            system_prompt=system_prompt,
+            tool_selection=tool_selection,
+            model=model,
+        )
+        self.config.create(definition, expected_revision=expected_revision)
+        return self.list(tools=tools)
+
+    def update(
+        self,
+        *,
+        agent_id: str,
+        name: str,
+        description: str,
+        system_prompt: str,
+        tool_selection: ToolSelection,
+        model: str | None,
+        tools: ToolRegistry,
+        expected_revision: int,
+    ) -> AgentDefinitionCatalogView:
+        if agent_id == GENERAL_AGENT_DEFINITION.agent_id:
+            raise ConfigError(f"builtin agent definition is immutable: {agent_id}")
+        self._require_known_selected_tools(tool_selection, tools)
+        current = next(
+            (item for item in self.config.snapshot().definitions if item.agent_id == agent_id),
+            None,
+        )
+        if current is None:
+            raise ConfigError(f"agent definition not found: {agent_id}")
+        updated = AgentDefinition(
+            agent_id=agent_id,
+            name=name,
+            description=description,
+            system_prompt=system_prompt,
+            tool_selection=tool_selection,
+            model=model,
+            can_spawn=current.can_spawn,
+            default_budget=current.default_budget,
+        )
+        self.config.update(updated, expected_revision=expected_revision)
+        return self.list(tools=tools)
+
+    def delete(
+        self,
+        agent_id: str,
+        *,
+        expected_revision: int,
+        tools: ToolRegistry | None = None,
+    ) -> AgentDefinitionCatalogView:
+        if agent_id == GENERAL_AGENT_DEFINITION.agent_id:
+            raise ConfigError(f"builtin agent definition is immutable: {agent_id}")
+        self.config.delete(agent_id, expected_revision=expected_revision)
+        return self.list(tools=tools or ToolRegistry())
+
+    def copy_builtin(
+        self,
+        agent_id: str,
+        *,
+        new_agent_id: str,
+        name: str,
+        tools: ToolRegistry,
+        expected_revision: int,
+    ) -> AgentDefinitionCatalogView:
+        if agent_id != GENERAL_AGENT_DEFINITION.agent_id:
+            raise ConfigError(f"builtin agent definition not found: {agent_id}")
+        copied = AgentDefinition(
+            **{
+                **GENERAL_AGENT_DEFINITION.model_dump(exclude={"contract_hash"}),
+                "agent_id": new_agent_id,
+                "name": name,
+            }
+        )
+        self.config.create(copied, expected_revision=expected_revision)
+        return self.list(tools=tools)
+
+    def tool_options(self, tools: ToolRegistry) -> tuple[AgentToolOptionView, ...]:
+        return tuple(
+            AgentToolOptionView(
+                name=definition.name,
+                description=definition.description,
+                effect=definition.effect,
+                owner_id=self._owner_id(tools, definition.name),
+                execution_contract_hash=self.tool_reference(
+                    tools, definition
+                ).execution_contract_hash,
+            )
+            for definition in self._candidate_definitions(tools)
+        )
+
+    def catalog_snapshot(
+        self,
+        tools: ToolRegistry,
+        *,
+        permission_overrides: Mapping[str, PermissionMode] | None = None,
+        plugin_permission_overrides: Mapping[str, PermissionMode] | None = None,
+        approval_mode: SessionApprovalMode = "inherit",
+    ) -> AgentCatalogSnapshot:
+        config = self.config.snapshot()
+        return AgentCatalogSnapshot(
+            revision=config.revision,
+            entries=self._entries(
+                tools,
+                permission_overrides=permission_overrides,
+                plugin_permission_overrides=plugin_permission_overrides,
+                approval_mode=approval_mode,
+            ),
+        )
+
+    def _entries(
+        self,
+        tools: ToolRegistry,
+        *,
+        permission_overrides: Mapping[str, PermissionMode] | None = None,
+        plugin_permission_overrides: Mapping[str, PermissionMode] | None = None,
+        approval_mode: SessionApprovalMode = "inherit",
+    ) -> tuple[AgentCatalogEntry, ...]:
+        config = self.config.snapshot()
+        overrides = permission_overrides or {}
+        plugin_overrides = plugin_permission_overrides or {}
+        definitions = (GENERAL_AGENT_DEFINITION, *config.definitions)
+        candidates = {
+            definition.name: definition for definition in self._candidate_definitions(tools)
+        }
+        entries: list[AgentCatalogEntry] = []
+        for definition in definitions:
+            selected_names = (
+                tuple(candidates)
+                if definition.tool_selection.mode == "all"
+                else definition.tool_selection.names
+            )
+            missing = tuple(name for name in selected_names if name not in candidates)
+            effective: list[EffectiveToolRef] = []
+            for name in selected_names:
+                if name not in candidates:
+                    continue
+                tool = candidates[name]
+                raw_plugin_id = tool.metadata.get("plugin_id")
+                plugin_id = (
+                    raw_plugin_id if isinstance(raw_plugin_id, str) and raw_plugin_id else None
+                )
+                permission = resolve_tool_permission(
+                    tool.permission_mode,
+                    approval_mode,
+                    permission_control=tool.permission_control,
+                    override=configured_tool_permission(
+                        name,
+                        plugin_id,
+                        tool_overrides=overrides,
+                        plugin_overrides=plugin_overrides,
+                    ),
+                )
+                if permission == "deny":
+                    continue
+                effective.append(
+                    self.tool_reference(
+                        tools,
+                        tool,
+                        minimum_permission_mode=permission,
+                    )
+                )
+            entries.append(
+                AgentCatalogEntry(
+                    definition=definition,
+                    effective_tools=tuple(effective),
+                    missing_tool_names=missing,
+                )
+            )
+        return tuple(entries)
+
+    @staticmethod
+    def _candidate_definitions(tools: ToolRegistry) -> tuple[ToolDefinition, ...]:
+        return tuple(
+            definition
+            for definition in tools.definitions()
+            if definition.name not in AGENT_CONTROL_TOOL_NAMES
+        )
+
+    @classmethod
+    def tool_reference(
+        cls,
+        tools: ToolRegistry,
+        definition: ToolDefinition,
+        *,
+        minimum_permission_mode: PermissionMode = "auto",
+    ) -> EffectiveToolRef:
+        metadata = definition.metadata
+        plugin_id = metadata.get("plugin_id")
+        contribution_id = metadata.get("contribution_id")
+        canonical_id = (
+            f"{plugin_id}/tools/{contribution_id}"
+            if isinstance(plugin_id, str) and isinstance(contribution_id, str)
+            else f"ouro.host/tools/{definition.name}"
+        )
+        execution_hash = metadata.get("execution_contract_hash")
+        raw_plugin_permissions = metadata.get("plugin_permissions", ())
+        plugin_permissions = (
+            frozenset(item for item in raw_plugin_permissions if isinstance(item, str))
+            if isinstance(raw_plugin_permissions, (list, tuple))
+            else frozenset()
+        )
+        is_shell = isinstance(metadata.get("shell_kind"), str)
+        is_mcp = definition.source == "mcp"
+        return EffectiveToolRef(
+            public_name=definition.name,
+            canonical_tool_id=canonical_id,
+            owner_id=cls._owner_id(tools, definition.name),
+            execution_contract_hash=(
+                execution_hash
+                if isinstance(execution_hash, str) and execution_hash
+                else tool_definition_contract_hash(definition)
+            ),
+            source=definition.source,
+            effect=definition.effect,
+            minimum_permission_mode=minimum_permission_mode,
+            requires_network=(is_shell or is_mcp or "network.outbound" in plugin_permissions),
+            requires_mcp=is_mcp,
+            requires_external_paths=(is_shell or is_mcp or "process.spawn" in plugin_permissions),
+        )
+
+    @staticmethod
+    def _owner_id(tools: ToolRegistry, name: str) -> str:
+        return tools.owner_of(name) or "ouro.host"
+
+    @staticmethod
+    def _require_known_selected_tools(
+        selection: ToolSelection,
+        tools: ToolRegistry,
+    ) -> None:
+        if selection.mode != "selected":
+            return
+        known = set(tools.names()) - AGENT_CONTROL_TOOL_NAMES
+        missing = sorted(set(selection.names) - known)
+        if missing:
+            raise ConfigError("unknown selected tools: " + ", ".join(missing))
+
+    @staticmethod
+    def _view(
+        entry: AgentCatalogEntry,
+        *,
+        source: str,
+    ) -> AgentDefinitionView:
+        return AgentDefinitionView(
+            agent_id=entry.definition.agent_id,
+            name=entry.definition.name,
+            description=entry.definition.description,
+            tool_selection=entry.definition.tool_selection,
+            model=entry.definition.model,
+            source="builtin" if source == "builtin" else "user",
+            editable=source == "user",
+            compatibility="available" if entry.available else "unavailable",
+            missing_tool_names=entry.missing_tool_names,
+            contract_hash=entry.definition.contract_hash,
+        )
+
+
+__all__ = ["AgentDefinitionService", "GENERAL_AGENT_DEFINITION"]

ouro/application/agent_execution.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Protocol
+
+from ouro.application.events import ApplicationEventPublisher
+from ouro.application.supervisor_models import RunHandle, RuntimeStatusSnapshot
+from ouro.core.agents import DelegationRecord
+from ouro.core.callbacks import run_blocking
+from ouro.core.errors import DelegationRevisionConflictError, PersistenceError, SessionBusyError
+from ouro.core.redaction import redact_text
+from ouro.core.state import RunRecord
+from ouro.sessions import SessionStore
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class RunObserver(Protocol):
+    async def wait_run(self, session_id: str, run_id: str) -> RunRecord: ...
+
+    async def wait(self, handle: RunHandle) -> RuntimeStatusSnapshot: ...
+
+    def release_handle(self, handle: RunHandle) -> None: ...
+
+
+class AgentExecutionTasks:
+    """Own result settlement tasks by durable child Run identity.
+
+    Retries are bounded and scoped to observed delegations. Pending delivery
+    remains durable after exhaustion and can be retried by targeted recovery.
+    No Session enumeration, per-token checkpoint reads, or extra polling loop.
+    """
+
+    def __init__(
+        self,
+        store: SessionStore,
+        observer: RunObserver,
+        events: ApplicationEventPublisher,
+        settle: Callable[[DelegationRecord], Awaitable[object]],
+    ) -> None:
+        self.store = store
+        self.observer = observer
+        self.events = events
+        self.settle = settle
+        self._tasks: dict[tuple[str, str], asyncio.Task[None]] = {}
+        self._receipts: set[asyncio.Task[None]] = set()
+        self._closed = False
+
+    def watch(self, relation: DelegationRecord) -> None:
+        if (
+            self._closed
+            or relation.child_session_id is None
+            or relation.current_child_run_id is None
+            or (relation.result is not None and relation.result.delivery.status != "pending")
+        ):
+            return
+        key = relation.delegation_id, relation.current_child_run_id
+        current = self._tasks.get(key)
+        if current is not None and not current.done():
+            return
+        task = asyncio.create_task(self._observe(relation), name=f"ouro-agent-result-{key[1]}")
+        self._tasks[key] = task
+        task.add_done_callback(lambda done: self._finished(key, done))
+
+    def own_receipt(self, handle: RunHandle) -> None:
+        """Release private process receipts; result waits use durable identity."""
+        if self._closed:
+            return
+
+        async def release() -> None:
+            await self.observer.wait(handle)
+            self.observer.release_handle(handle)
+
+        task = asyncio.create_task(release(), name=f"ouro-agent-receipt-{handle.handle_id}")
+        self._receipts.add(task)
+        task.add_done_callback(self._receipt_finished)
+
+    def _receipt_finished(self, task: asyncio.Task[None]) -> None:
+        self._receipts.discard(task)
+        if not task.cancelled() and task.exception() is not None:
+            _LOGGER.error("Agent receipt cleanup failed: %s", type(task.exception()).__name__)
+
+    async def close(self) -> None:
+        self._closed = True
+        tasks = (*self._tasks.values(), *self._receipts)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        self._tasks.clear()
+        self._receipts.clear()
+
+    def _finished(self, key: tuple[str, str], task: asyncio.Task[None]) -> None:
+        if self._tasks.get(key) is task:
+            self._tasks.pop(key)
+        if not task.cancelled() and task.exception() is not None:
+            # Reporting itself can fail if storage is unavailable. Keep this
+            # visible without logging prompts, tool payloads, or raw exceptions.
+            _LOGGER.error(
+                "Agent settlement reporting failed: %s (%s)", key, type(task.exception()).__name__
+            )
+
+    async def _observe(self, relation: DelegationRecord) -> None:
+        async def settle() -> object:
+            assert (
+                relation.child_session_id is not None and relation.current_child_run_id is not None
+            )
+            await self.observer.wait_run(relation.child_session_id, relation.current_child_run_id)
+            return await self.settle(relation)
+
+        await self.retry(relation, settle)
+
+    async def retry(
+        self, relation: DelegationRecord, operation: Callable[[], Awaitable[object]]
+    ) -> None:
+        for attempt, delay in enumerate((0, 0.1, 0.5, 2.0)):
+            if delay:
+                await asyncio.sleep(delay)
+            try:
+                await operation()
+                return
+            except Exception as exc:
+                retryable = isinstance(exc, (OSError, PersistenceError, SessionBusyError))
+                error = f"{type(exc).__name__}: {redact_text(str(exc))}"[:4_000]
+                try:
+                    await run_blocking(self._retain_error, relation, error)
+                except OSError, PersistenceError:
+                    # The failed dependency may be the same store used for
+                    # diagnostics. Still spend only the bounded retry budget.
+                    if retryable and attempt < 3:
+                        continue
+                    raise
+                if retryable and attempt < 3:
+                    continue
+                await self.events.publish(
+                    session_id=relation.root_session_id,
+                    run_id=relation.parent_run_id,
+                    event_type="diagnostic",
+                    payload={
+                        "code": "agent_result_delivery_incomplete",
+                        "severity": "error",
+                        "component": "application.agents",
+                        "delegation_id": relation.delegation_id,
+                        "child_run_id": relation.current_child_run_id,
+                        "error": error,
+                        "recoverable": True,
+                        "suggested_action": "Reconcile this root Session to retry settlement.",
+                    },
+                )
+                return
+
+    def _retain_error(self, relation: DelegationRecord, error: str) -> None:
+        for _ in range(3):
+            current = self.store.load_delegation(relation.root_session_id, relation.delegation_id)
+            result = current.result
+            if (
+                result is None
+                or result.child_run_id != relation.current_child_run_id
+                or result.delivery.status != "pending"
+            ):
+                return
+            try:
+                self.store.save_delegation(
+                    current.model_copy(
+                        update={
+                            "result": result.model_copy(
+                                update={
+                                    "delivery": result.delivery.model_copy(update={"error": error})
+                                }
+                            )
+                        }
+                    ),
+                    expected_revision=current.revision,
+                )
+                return
+            except DelegationRevisionConflictError:
+                continue
+        raise DelegationRevisionConflictError("Could not retain pending result delivery error")