contraagent 0.1.0__py3-none-any.whl

contraagent/__init__.py

@@ -0,0 +1,99 @@
+"""contraagent: run coding-agent CLIs as typed, supervised, observable tasks.
+
+A pipeline declares its tasks (parameters, output, budget), implements each agent task as
+a plugin, and writes the flow as a plain function:
+
+    from contraagent import Pipeline, agent_task
+
+    summarize = agent_task("summarize", plugin="plugins/summarize", params=Doc, output=Summary)
+
+    def docs(units):
+        for u in units:
+            summarize(u, path=f"in/{u}.md")
+
+    Pipeline("pipeline.toml").run(docs, units=["alpha", "beta"])
+
+The public modules: `contraagent` (this one: tasks, flows, the pipeline, validators, the
+values callbacks are given, the errors), `contraagent.config` (credentials, routes,
+budgets, quota readings), `contraagent.backends` (the coding agents), `contraagent.engine`
+(the runners and schedulers underneath a pipeline), `contraagent.plugins`,
+`contraagent.monitor` (with `contraagent.monitor.api`, its HTTP responses) and
+`contraagent.testing`. `contraagent docs` prints the documentation.
+"""
+
+from contraagent._internal.backends.credentials import CredentialError
+from contraagent._internal.backends.process import LaunchError
+from contraagent._internal.contracts.validators import CommandValidator, Validator
+from contraagent._internal.dispatch.flow import TaskDeferred, TaskFailed, time_box
+from contraagent._internal.dispatch.interceptors import ResultEnricher, TaskScope
+from contraagent._internal.dispatch.records import Changes, DeferralCause, Frame, Hop, Loop, OtherModel, SkippedHop, TokenUsage
+from contraagent._internal.dispatch.task import Origin, Partial, Task, TaskResult, TimeBox
+from contraagent._internal.errors import ContraagentDeprecationWarning, ContraagentError
+from contraagent._internal.execution.pipeline_files import NoCurrentRun, log, pipeline_table, save
+from contraagent._internal.execution.recording import RecordingError
+from contraagent._internal.execution.run import RunExists, RunFormatError, RunLocked
+from contraagent._internal.pipeline.check import CheckReport
+from contraagent._internal.pipeline.graph import Pending, TextOutput, TooManyPasses
+from contraagent._internal.pipeline.pipeline import Pipeline, RunReport
+from contraagent._internal.pipeline.spec import AgentTask, PythonTask, agent_task, python_task
+from contraagent._internal.plugins.plugin import PluginError
+from contraagent._internal.public import publish
+from contraagent._internal.routing.config import ConfigError, PerTask, PipelineConfig
+from contraagent._internal.routing.plan import Overrides, RoutingError
+from contraagent._internal.routing.preflight import PreflightStopped
+from contraagent._internal.routing.quota import QuotaRule
+
+__all__ = [
+    "AgentTask",
+    "Changes",
+    "CheckReport",
+    "CommandValidator",
+    "ConfigError",
+    "ContraagentDeprecationWarning",
+    "ContraagentError",
+    "CredentialError",
+    "DeferralCause",
+    "Frame",
+    "Hop",
+    "LaunchError",
+    "Loop",
+    "NoCurrentRun",
+    "Origin",
+    "OtherModel",
+    "Overrides",
+    "Partial",
+    "Pending",
+    "PerTask",
+    "Pipeline",
+    "PipelineConfig",
+    "PluginError",
+    "PreflightStopped",
+    "PythonTask",
+    "QuotaRule",
+    "RecordingError",
+    "ResultEnricher",
+    "RoutingError",
+    "RunExists",
+    "RunFormatError",
+    "RunLocked",
+    "RunReport",
+    "SkippedHop",
+    "Task",
+    "TaskDeferred",
+    "TaskFailed",
+    "TaskResult",
+    "TaskScope",
+    "TextOutput",
+    "TimeBox",
+    "TokenUsage",
+    "TooManyPasses",
+    "Validator",
+    "agent_task",
+    "log",
+    "pipeline_table",
+    "python_task",
+    "save",
+    "time_box",
+]
+
+publish(__name__, __all__)

contraagent/__main__.py

@@ -0,0 +1,3 @@
+from contraagent._internal.cli import main
+
+raise SystemExit(main())

contraagent/_internal/__init__.py

@@ -0,0 +1,43 @@
+"""contraagent's implementation. The public modules (`contraagent`, `contraagent.config`,
+`contraagent.backends`, `contraagent.engine`, `contraagent.plugins`, `contraagent.monitor`,
+`contraagent.monitor.api`, `contraagent.testing`) re-export from it; nothing here imports
+one of them.
+
+Layers, bottom up (each imports only the ones above it in this list):
+
+* `errors`      `ContraagentError`, the base of every error raised on purpose
+* `platform/`   the host, on Linux, macOS and Windows alike: its processes (`processes`),
+                a child in a group of its own (`groups`), a file lock (`locks`), and the
+                line and variables that name a live agent process's run and task
+                (`telemetry`, `envvars`); leaf modules, importing nothing else of the package
+* `commandline` the parts every command's arguments share; a leaf module
+* `public`      how a public module publishes what it re-exports
+* `docs`        the documentation installed with the package (`contraagent/docs/`): its
+                topics and the examples they quote; `contraagent docs`
+* `runs/`       run records: the layout of a run directory, the one writer of a document
+                and of a log line, the readers of complete lines, the times records hold;
+                `RunSource` (where runs are read from) and `Liveness`
+* `dispatch/`   the domain-free `Task`/`TaskResult` envelope and the schedulers:
+                `WorkQueue` (claims, caps, retry, throttle, deadline, bottom level, priority)
+                and `FlowDriver` (generator flows over it); `make_python_task`; `records`: the
+                facts a run records (hops, rests, deferral causes, flow paths), one type each
+* `backends/`   one coding-agent CLI behind `Backend`: one `Launch` in, one `LaunchResult` out
+* `contracts/`  `OutputContract`/`InputContract` (`contract`): files checked by pydantic and
+                `validators`; `run_until_valid` resumes the session until they hold;
+                `calls`: the call file an agent task is handed; `pointers`: the parts of a
+                JSON output a task keeps (`agent_task(preserve=)`)
+* `routing/`    `PipelineConfig` (one TOML file) -> `RoutingPlan`: per-kind
+                `KindConfig` and failover `Router`, with a preflight
+* `execution/`  `AgentRunner` (one task, with failover), `RetryingRunner`, `PythonTaskRunner`,
+                `TaskAdapter`, `Run` (journal, lock, plan, resume), `CursorStore`
+* `plugins/`    an agent task's implementation, as the coding agent loads it;
+                hooks declared once and rendered into each agent's own hook system
+* `pipeline/`   `agent_task`, `@python_task`, `Pipeline`: the API a pipeline is written in
+* `monitor/`    a read-only live view of a run, as a library and a web UI (`static/`, built
+                from `web/`) with its OpenAPI document (`openapi.json`)
+* `hub/`        the runs of many hosts in one monitor: `contraagent relay` ships a host's runs,
+                `contraagent hub` stores them and serves their monitor; only `hub/server.py`,
+                which serves the monitor's app, imports `monitor/`
+* `testing`     `StubAgent`: a coding agent that plays scripted replies, for tests
+* `cli`         `contraagent ...`: one argument tree over every command
+"""

contraagent/_internal/backends/__init__.py

@@ -0,0 +1,119 @@
+"""Coding-agent CLIs behind one interface: one `Launch` in, one `LaunchResult` out.
+
+* `base.py`         the `Backend` ABC and its one run template (`Backend.run`)
+* `launch.py`       the backend-neutral vocabulary: `Launch`, `Limits`, `LaunchResult`, `Stop`, `Usage`
+* `wire.py`         what every wire reader shares: `EventFold`, `LimitsWatch`, the tool preview
+* `refusal.py`      how a launch ended: `Signals`, `Ending`, the one `classify_stop` ladder
+* `credentials.py`  credential types (subscription, API key, OAuth token, WIF, Bedrock, ...) and secrets
+* `process.py`      the guarded subprocess loop every CLI backend shares
+* `live_processes.py`  the agent processes this interpreter started, for teardown
+* `streams.py`      raw transcript lines -> the monitor's renderable events
+* `plugin_files.py` a plugin's MCP servers and extensions, as every backend reads them
+* `opencode_key.py` an OpenCode key, wherever an agent finds it: its account and its usage
+* `claude/`, `omp/`, `opencode/`, `pi/`, `codex/`  the concrete CLIs: `backend.py` (argv, env,
+  credentials), `wire.py` (the reader and the monitor's view of its events), `catalogue.py`
+  (the model list), `login.py` (a login it keeps)
+
+The registry below is the one place a coding-agent *name* (what a config
+file, a `Route` or a journal row says) is tied to a class. Everything that
+needs the list of known agents reads it from here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contraagent._internal.backends.base import Backend
+from contraagent._internal.backends.claude import ClaudeBackend
+from contraagent._internal.backends.codex import CodexBackend
+from contraagent._internal.backends.credentials import (
+    AMBIENT,
+    Ambient,
+    ApiKey,
+    Bedrock,
+    Credential,
+    CredentialBinding,
+    CredentialError,
+    Gateway,
+    OAuthToken,
+    Pool,
+    Secret,
+    Subscription,
+    Vertex,
+    WorkloadIdentity,
+)
+from contraagent._internal.backends.launch import STDIN_THRESHOLD, Launch, LaunchResult, Limits, QuotaRefusal, Stop, Usage
+from contraagent._internal.backends.omp import OMP_PREAMBLE, OmpBackend, OmpRpcBackend
+from contraagent._internal.backends.opencode import OpencodeBackend
+from contraagent._internal.backends.pi import PiBackend
+from contraagent._internal.backends.process import LaunchError
+
+_REGISTRY: dict[str, type[Backend]] = {
+    "claude": ClaudeBackend,
+    "omp": OmpBackend,
+    "omp-rpc": OmpRpcBackend,
+    "opencode": OpencodeBackend,
+    "pi": PiBackend,
+    "codex": CodexBackend,
+}
+
+
+def register_backend(name: str, cls: type[Backend]) -> None:
+    """Make a custom `Backend` subclass known by `name` (config files, routes, `create_backend`)."""
+    _REGISTRY[name] = cls
+
+
+def backend_class(name: str) -> type[Backend] | None:
+    """The class registered under `name`, or None."""
+    return _REGISTRY.get(name)
+
+
+def known_agents() -> tuple[str, ...]:
+    """Every registered coding-agent name, in registration order."""
+    return tuple(_REGISTRY)
+
+
+def create_backend(name: str, **kwargs: Any) -> Backend:
+    """A new backend for a registered name. Unknown names raise KeyError."""
+    cls = _REGISTRY.get(name)
+    if cls is None:
+        raise KeyError(f"unknown backend: {name} (known: {', '.join(_REGISTRY)})")
+    return cls(**kwargs)
+
+
+__all__ = [
+    "AMBIENT",
+    "OMP_PREAMBLE",
+    "STDIN_THRESHOLD",
+    "Ambient",
+    "ApiKey",
+    "Backend",
+    "Bedrock",
+    "ClaudeBackend",
+    "CodexBackend",
+    "Credential",
+    "CredentialBinding",
+    "CredentialError",
+    "Gateway",
+    "Launch",
+    "LaunchError",
+    "LaunchResult",
+    "Limits",
+    "OAuthToken",
+    "OmpBackend",
+    "OmpRpcBackend",
+    "OpencodeBackend",
+    "PiBackend",
+    "Pool",
+    "QuotaRefusal",
+    "Secret",
+    "Stop",
+    "Subscription",
+    "Usage",
+    "Vertex",
+    "WorkloadIdentity",
+    "backend_class",
+    "create_backend",
+    "known_agents",
+    "register_backend",
+]