agentplane-control-plane 0.1.0__tar.gz

agentplane_control_plane-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check control_plane tests
+      - name: Test
+        run: pytest -v

agentplane_control_plane-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,129 @@
+name: Release
+
+# One-shot release: optional tag input → verify → build → tag → GitHub Release → PyPI.
+# See RELEASING.md for Trusted Publisher setup.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag (e.g. v0.1.0). Leave empty to use v{version} from pyproject.toml."
+        required: false
+        type: string
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      tag: ${{ steps.meta.outputs.tag }}
+      version: ${{ steps.meta.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Resolve tag and verify against pyproject
+        id: meta
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          version="$(grep -m1 '^version' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')"
+          init="$(grep -m1 '__version__' control_plane/__init__.py | sed -E 's/.*"([^"]+)".*/\1/')"
+          if [ "$init" != "$version" ]; then
+            echo "::error::__version__ ($init) does not match pyproject version ($version)."
+            exit 1
+          fi
+          if [ -n "${INPUT_TAG}" ]; then
+            tag="${INPUT_TAG}"
+          else
+            tag="v${version}"
+          fi
+          case "$tag" in
+            v*) ;;
+            *) tag="v${tag}" ;;
+          esac
+          tag_version="${tag#v}"
+          echo "tag: $tag | pyproject version: $version | sha: $GITHUB_SHA"
+          if [ "$tag_version" != "$version" ]; then
+            echo "::error::Tag $tag does not match pyproject version $version. Bump version (and __version__) and merge before releasing."
+            exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Build sdist and wheel
+        run: |
+          pip install "build>=1.2"
+          python -m build
+
+      - name: Check metadata
+        run: |
+          pip install "twine>=6"
+          twine check dist/*
+
+      - name: Create tag and GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.meta.outputs.tag }}
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          if git rev-parse "refs/tags/${TAG}" >/dev/null 2>&1; then
+            existing="$(git rev-list -n 1 "${TAG}")"
+            if [ "$existing" != "$GITHUB_SHA" ]; then
+              echo "::error::Tag ${TAG} already exists on $existing, not $GITHUB_SHA."
+              exit 1
+            fi
+            echo "Tag ${TAG} already points at this commit; reusing."
+          else
+            git tag "${TAG}" "$GITHUB_SHA"
+            git push origin "refs/tags/${TAG}"
+          fi
+
+          if gh release view "${TAG}" >/dev/null 2>&1; then
+            echo "::error::GitHub Release ${TAG} already exists. Delete it or bump the version."
+            exit 1
+          fi
+
+          gh release create "${TAG}" dist/* \
+            --title "agentplane-control-plane ${VERSION}" \
+            --generate-notes \
+            --target "$GITHUB_SHA"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agentplane-control-plane/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentplane_control_plane-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.db
+*.db-*
+.DS_Store
+.env
+.streamlit/secrets.toml

agentplane_control_plane-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] — 2026-08-14
+
+- First PyPI release of the shared AgentPlane control plane.
+- SQLite stays in this process; Chronicle and TokenOps talk over HTTP.
+- HTML UI (Admin, Chronicle waterfall, TokenOps) served with the API.

agentplane_control_plane-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentplane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentplane_control_plane-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: agentplane-control-plane
+Version: 0.1.0
+Summary: Shared AgentPlane control plane: Chronicle envelopes + TokenOps governance over HTTP.
+Project-URL: Homepage, https://github.com/theagentplane/control-plane
+Project-URL: Repository, https://github.com/theagentplane/control-plane
+Project-URL: Issues, https://github.com/theagentplane/control-plane/issues
+Project-URL: Changelog, https://github.com/theagentplane/control-plane/blob/main/CHANGELOG.md
+Author: Susheem Koul, Tisha Chawla
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,chronicle,control-plane,governance,llm,observability,tokenops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: uvicorn[standard]>=0.32
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.15.22; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Provides-Extra: ui
+Requires-Dist: pandas>=2; extra == 'ui'
+Requires-Dist: streamlit>=1.32; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# AgentPlane Control Plane
+
+Shared HTTP control plane for **Chronicle** and **TokenOps**. SQLite lives
+**only** in this process. Agents never open the database file.
+
+Design: [`docs/DESIGN.md`](docs/DESIGN.md) · Issue: [#2](https://github.com/theagentplane/control-plane/issues/2)
+
+## Install
+
+```bash
+pip install agentplane-control-plane
+control-plane serve --port 8800 --db control_plane.db
+```
+
+From a clone:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+control-plane serve --port 8800 --db control_plane.db
+```
+
+Open http://127.0.0.1:8800/ — Admin, Chronicle, TokenOps tabs. No login.
+
+Sidecars:
+
+```bash
+export CONTROL_PLANE_URL=http://127.0.0.1:8800
+# Chronicle
+chronicle.record("run", store=RemoteStore(os.environ["CONTROL_PLANE_URL"], batch_size=1))
+# TokenOps
+export TOKENOPS_URL=http://127.0.0.1:8800
+# TOKENOPS_EMBEDDED must be unset
+```
+
+## API callers
+
+| Route | Caller |
+|---|---|
+| `POST /v1/envelopes:batch` | Chronicle sidecar (only ingest API; `batch_size=1` = immediate flush) |
+| `GET /v1/traces/{id}/envelopes` | Chronicle sidecar (fixture replay) and Chronicle UI waterfall |
+| `GET /v1/traces` | Chronicle UI search |
+| `POST /v1/runs`, ledger, governance, run-records | TokenOps sidecar |
+| segments / budgets / policies, admin keys | UI |
+
+Auth off when no keys exist (local). Create keys in Admin, or:
+
+```bash
+export CONTROL_PLANE_API_KEYS='chron:local:ingest+read,tops:local:ingest+read,admin:local:read+admin'
+export CONTROL_PLANE_API_KEY=chron   # sidecar
+```
+
+## Local SQLite
+
+Default is a file next to the server (`CONTROL_PLANE_DB`). Do not point TokenOps
+or Chronicle at that file. Unit tests in those repos keep their own sqlite/jsonl
+when `TOKENOPS_EMBEDDED=1` / local Chronicle stores.

agentplane_control_plane-0.1.0/README.md

@@ -0,0 +1,57 @@
+# AgentPlane Control Plane
+
+Shared HTTP control plane for **Chronicle** and **TokenOps**. SQLite lives
+**only** in this process. Agents never open the database file.
+
+Design: [`docs/DESIGN.md`](docs/DESIGN.md) · Issue: [#2](https://github.com/theagentplane/control-plane/issues/2)
+
+## Install
+
+```bash
+pip install agentplane-control-plane
+control-plane serve --port 8800 --db control_plane.db
+```
+
+From a clone:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+control-plane serve --port 8800 --db control_plane.db
+```
+
+Open http://127.0.0.1:8800/ — Admin, Chronicle, TokenOps tabs. No login.
+
+Sidecars:
+
+```bash
+export CONTROL_PLANE_URL=http://127.0.0.1:8800
+# Chronicle
+chronicle.record("run", store=RemoteStore(os.environ["CONTROL_PLANE_URL"], batch_size=1))
+# TokenOps
+export TOKENOPS_URL=http://127.0.0.1:8800
+# TOKENOPS_EMBEDDED must be unset
+```
+
+## API callers
+
+| Route | Caller |
+|---|---|
+| `POST /v1/envelopes:batch` | Chronicle sidecar (only ingest API; `batch_size=1` = immediate flush) |
+| `GET /v1/traces/{id}/envelopes` | Chronicle sidecar (fixture replay) and Chronicle UI waterfall |
+| `GET /v1/traces` | Chronicle UI search |
+| `POST /v1/runs`, ledger, governance, run-records | TokenOps sidecar |
+| segments / budgets / policies, admin keys | UI |
+
+Auth off when no keys exist (local). Create keys in Admin, or:
+
+```bash
+export CONTROL_PLANE_API_KEYS='chron:local:ingest+read,tops:local:ingest+read,admin:local:read+admin'
+export CONTROL_PLANE_API_KEY=chron   # sidecar
+```
+
+## Local SQLite
+
+Default is a file next to the server (`CONTROL_PLANE_DB`). Do not point TokenOps
+or Chronicle at that file. Unit tests in those repos keep their own sqlite/jsonl
+when `TOKENOPS_EMBEDDED=1` / local Chronicle stores.

agentplane_control_plane-0.1.0/RELEASING.md

@@ -0,0 +1,80 @@
+# Releasing
+
+The control plane publishes to PyPI as **`agentplane-control-plane`**
+(CLI: `control-plane`, import: `control_plane`) using GitHub Actions with
+**Trusted Publishing (OIDC)** — no API tokens are stored anywhere. Same
+pattern as Chronicle (`agent-chronicle`) and TokenOps (`agent-tokenops`).
+
+One workflow run is atomic: **verify → build → git tag → GitHub Release → PyPI**.
+
+## One-time setup (Trusted Publishing)
+
+### 1. Pending publisher on PyPI
+
+1. Sign in at [pypi.org](https://pypi.org) (account that will own the project).
+2. Open [Publishing](https://pypi.org/manage/account/publishing/)
+   (*Your account* → *Publishing*).
+3. Under **Add a new pending publisher**, choose **GitHub** and fill in:
+   - PyPI project name: `agentplane-control-plane`
+   - Owner: `theagentplane`
+   - Repository: `control-plane`
+   - Workflow filename: `release.yml`
+   - Environment name: `pypi`
+4. Save. The project does **not** exist yet; the first successful CI upload
+   creates it and binds that publisher permanently.
+
+Optional: do the same on [TestPyPI](https://test.pypi.org/manage/account/publishing/)
+for a dry run (same project name `agentplane-control-plane`).
+
+### 2. GitHub Environment
+
+In the `theagentplane/control-plane` repo:
+
+1. **Settings → Environments → New environment**
+2. Name it exactly `pypi` (must match `environment: pypi` in `release.yml` and
+   the PyPI publisher form).
+3. Optional: add required reviewers so a human must approve before upload.
+
+No secrets needed — OIDC uses `permissions: id-token: write` in `release.yml`.
+
+## Cutting a release
+
+1. Move the `CHANGELOG.md` `[Unreleased]` items under a new version heading with
+   today's date; start a fresh empty `[Unreleased]`.
+2. Bump `version` in `pyproject.toml` **and** `__version__` in
+   `control_plane/__init__.py` following SemVer. Commit and merge to `main`.
+3. In GitHub: **Actions → Release → Run workflow**
+   - Branch: `main` (the commit that has the version bump)
+   - Tag (optional): e.g. `v0.1.0` — leave empty to use `v{version}` from
+     `pyproject.toml`
+4. The workflow will, in one run:
+   1. Require the tag to match `pyproject.toml` and `__version__`
+   2. Build sdist/wheel and `twine check`
+   3. Create and push the git tag
+   4. Create the GitHub Release (attaches dist artifacts)
+   5. Upload to PyPI (may wait on `pypi` environment approval)
+5. Verify:
+   ```bash
+   pip install agentplane-control-plane==X.Y.Z
+   python -c "import control_plane; print(control_plane.__version__)"
+   control-plane --help
+   ```
+
+## Version matching (why the workflow checks)
+
+PyPI versions are **immutable** and come from metadata inside the built wheel —
+that metadata is read from `pyproject.toml` at build time. The git tag
+(`v0.1.0`) is only a label; it does **not** set the package version.
+
+If you passed tag `v0.1.1` but `pyproject.toml` still says `0.1.0`, the workflow
+refuses to continue. Empty tag input defaults to `v` + the pyproject version.
+
+Also keep `control_plane.__version__` in sync so runtime version matches pip.
+
+## Versioning notes
+
+- Stay in `0.x` while the HTTP contract may still change.
+- Install name: `agentplane-control-plane`. Import name: `control_plane`.
+  CLI: `control-plane`.
+- Do not create tags or GitHub Releases by hand for normal cuts — use
+  **Run workflow** so tag, Release, and PyPI stay in lockstep.

agentplane_control_plane-0.1.0/config/default.yaml

@@ -0,0 +1,37 @@
+# TokenOps control plane seed. Consumed by tokenops.control.build_governor / Store auto-seed.
+# Budgets are spend caps bound to a segment; policies are the (detect, fix) templates.
+governance:
+  budgets:
+    - id: run_llm_cap
+      limit_micros: 2000000          # $2.00 per run; null/omitted -> unlimited accumulator
+      dimension: run
+  policies:
+    cost_budget:
+      budget: run_llm_cap
+    pre_call_worst_case:
+      budget: run_llm_cap
+      default_max_output: 1024
+    step_cap:
+      max_steps: 20
+    concurrency_cap:
+      max_concurrent: 4
+      mode: reject
+    tool_fix:
+      registry: [search]
+      k: 3
+    tool_output_cap:
+      cap_tokens: 8000
+    progress_guard:
+      window: 6
+      repeats: 3
+      max_corrections: 2
+    cost_guard:
+      budget: run_llm_cap
+      threshold: 0.8
+      mode: minimize
+    context_compaction:
+      ctx_max: 100000
+      has_hook: false
+    output_runaway:
+      repeats: 4
+      max_retries: 2

agentplane_control_plane-0.1.0/control_plane/__init__.py

@@ -0,0 +1,3 @@
+"""AgentPlane shared control plane — governance (TokenOps) + Chronicle envelopes."""
+
+__version__ = "0.1.0"