Soveren Agent Platform

Reusable runtime core for durable agent applications.

This repository contains the reusable runtime core shared by agent applications. It is intentionally separate from application repositories:

• soveren-agent-platform owns reusable mechanics: durable queueing, run tracking, decision/action framework, batching, scheduler, sessions, integration contracts, and bundled SQLite adapters for the default embedded runtime.
• poruchen owns private product behavior: prompts, ClickUp tools, approval copy, policies, and app-specific schema.
• pulsell-agent owns Pulsell-specific media, transcription, vision, task, and workflow behavior.

The current package contains:

• asynchronous SQLite adapters with internal serialized transactions
• durable queue port with a SQLite adapter
• layered migration runner with platform/app migration providers
• platform migrations for event_queue and agent_runs
• durable queue API
• inbound batching module with SQLite state and flush wakeups
• agent worker module that consumes queue events and calls app-provided agents
• cron module with atomic due-event publication and conversation-scoped cancellation
• Telegram interface module that normalizes Telegram ingress into queue events
• optional Telegram adapter for inbound normalization and outbound sending
• high-level Telegram agent bootstrap for default polling deployments
• optional Telegram polling runtime builder with message and callback hooks
• LLM backend contracts and reusable OpenAI-compatible/session-backed backends
• agent run persistence helpers
• durable planner decision reuse across dispatch retries
• optional one-accepted-decision receipts across model and prompt changes
• rich planner context builder for batches, sessions, mailbox, actions, outbound, cron, and routing metadata
• optional app-neutral prompt formatter for rich planner context
• planner envelope that injects session routing and rich context into LLM requests
• execution session mailbox for prompts queued behind busy sessions
• persistent execution-session events, snapshots, and deterministic routing
• reusable stub execution backend and a low-level tmux command-session utility that requires an explicit completion marker
• reusable Codex app-server execution session backend
• Docker-isolated Codex runtime for externally triggered work, with coarse resource profiles, persistent idle-stop lifecycle, and bounded egress
• packaged Codex sandbox image, per-conversation networks, and enforced shared egress boundary
• shared, tenant-isolated HTTP credential broker that keeps provider keys out of conversation sandboxes
• explicit app-neutral memory store and access-scoped Codex dynamic tools
• automatic conversation-scoped message history with FTS search, neighboring context, bounded searchable-history pruning, and read-only Codex dynamic tools
• Codex app-server dynamic tool contracts, registry, and fail-closed JSON-RPC tool-call handling
• session backend registry for wiring reusable and custom backends
• platform SQLite migration and schema compatibility checks
• generic actions/approvals lifecycle with app-registered executors
• generic outbound channel queue with app-registered senders
• explicit audited reconciliation for uncertain action and outbound effects
• decision dispatcher that maps typed decisions to outbound, actions, session mailbox, or cron side effects
• planner-dispatch helper for fake-tested context to side-effect pipelines
• runtime supervisor and AgentPlatformApp composition helper for standard platform workers

See Architecture for the current architecture. See Integration API for the consumer integration API and quick start. See Consuming App Guide for a practical consuming-app guide covering package dependency, Telegram wiring, and app-owned tools such as ClickUp. See Ports for the queue/store abstraction strategy. See Docker Sandbox Deployment for the Docker sandbox deployment path.

Installation

uv add "soveren-agent-platform>=0.12,<0.13"

Use soveren-agent-platform[telegram]>=0.12,<0.13 when the app uses the bundled Telegram adapter.

Consumer Quick Start

from pathlib import Path

from soveren_agent_platform.agent import AgentEvent, AgentHandler
from soveren_agent_platform.app_api import AgentPlatformApp


class AppAgentHandler(AgentHandler):
    async def handle(self, event: AgentEvent) -> None:
        ...


app = (
    AgentPlatformApp(db_path=Path("data/app.db"))
    .use_batching()
    .use_agent(handler=AppAgentHandler())
)

AgentPlatformApp applies and validates platform migrations before workers start. Apps with a separate migration pipeline can call await soveren_agent_platform.storage.bootstrap_platform_storage(db_path) themselves and pass bootstrap_storage=False.

Externally triggered Codex workloads must use AgentPlatformApp.configure_sandboxed_codex(...). Configure it once during application bootstrap and pass the returned runtime to PlannerRuntime. The AgentPlatformApp then owns conversation backend selection, registration, isolation, durable sessions, mailbox delivery, and shutdown. Provider credentials are resolved from trusted tenant_id; applications do not create Docker managers or Codex backend registries.

Local Development

uv sync --group dev
uv run ruff check src tests scripts
uv run mypy
uv run pytest

Release

Before the first release, run Bootstrap Runtime Packages from main. GitHub creates new GHCR packages as private and does not expose a package-visibility API. After the workflow creates all three bootstrap tags, set each package to Public in the organization package settings and rerun the workflow. Its anonymous pulls must pass.

1. Open a pull request into main; direct pushes are blocked.
2. Wait for Python 3.12, Python 3.13, sandbox smoke, and CodeQL checks.
3. Merge with squash or rebase after all conversations are resolved.
4. Confirm the three public bootstrap images remain anonymously pullable.
5. Create and push a tag matching the package version, for example v0.12.0.
6. Open the Publish workflow in GitHub Actions and approve the pending pypi deployment. PyPI authentication uses the configured trusted publisher, not a stored API token.

The pypi environment accepts only v* tags. The publish workflow additionally checks that the tag version matches pyproject.toml and that the tagged commit belongs to main. It fails before release validation unless all runtime package namespaces have already passed the anonymous bootstrap pull.