forge-agent-bridge 0.2.0__tar.gz

forge_agent_bridge-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  core:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: python -m ruff check src tests
+      - name: Tests
+        run: python -m pytest -q
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e .
+      - name: Dependency audit
+        run: |
+          pip install pip-audit
+          pip-audit --desc on
+      - name: SBOM (CycloneDX)
+        run: |
+          pip install "cyclonedx-bom>=7,<8"
+          cyclonedx-py environment "$(command -v python3)" --of JSON -o sbom.json
+          python -c "import json; json.load(open('sbom.json'))"
+          ls -l sbom.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sbom
+          path: sbom.json

forge_agent_bridge-0.2.0/.github/workflows/provider-homologation.yml

@@ -0,0 +1,39 @@
+name: Provider homologation
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 3 * * *"
+
+permissions:
+  contents: read
+
+jobs:
+  real-provider-matrix:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra dev
+      - name: Run redacted real-provider matrix
+        env:
+          # Provider credentials are configured only in the repository/org
+          # secret store by the operator. Missing auth is reported as blocked.
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_SESSION_TOKEN: ${{ secrets.AWS_SESSION_TOKEN }}
+          AWS_REGION: ${{ secrets.AWS_REGION }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run python scripts/provider_harness.py --real --output artifacts/provider-matrix.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: provider-homologation-${{ github.run_id }}
+          path: artifacts/provider-matrix.json

forge_agent_bridge-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,218 @@
+name: publish-pypi
+
+# Secure PyPI release pipeline — build once, publish the same artifact.
+#
+#   build   — version gate + `python -m build` + integrity manifest + artifact
+#             upload (contents:read only)
+#   publish — downloads the SAME dist/ built above, re-verifies sha256, then
+#             publishes via PyPI Trusted Publishing (OIDC — no stored token)
+#   verify  — installs the published version from PyPI in a clean venv and
+#             smoke-tests the console script
+#
+# Trusted Publishing (OIDC) — no stored token. The publisher registered on
+# PyPI must point to:
+#   owner/repo: EdgarSocrates98/forge-agent-bridge
+#   workflow:   publish-pypi.yml
+#   environment: release
+#
+# `environment: release` also enables repo protection — configure required
+# reviewers/rules under Settings > Environments > release.
+#
+# GitHub artifact attestations (PEP 740) are intentionally disabled to keep
+# this pipeline minimal; to enable later, add `attestations: write` to the
+# publish job permissions and `attestations: true` to the pypi-publish inputs.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to publish — must match the package version (pyproject or hatch source)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+# one publish run at a time — never cancel mid-publish
+concurrency:
+  group: publish-pypi
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build release artifact
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Version gate (input match, PyPI freshness, changelog)
+        env:
+          EXPECTED_VERSION: ${{ inputs.version }}
+        run: |
+          python - <<'PY'
+          import json, os, re, sys, tomllib, urllib.error, urllib.request
+
+          def fail(msg):
+              print(f"::error::version gate: {msg}")
+              sys.exit(1)
+
+          with open("pyproject.toml", "rb") as fh:
+              pyproject = tomllib.load(fh)
+          project = pyproject["project"]
+          name = project["name"]
+          version = project.get("version")
+          if version is None:
+              # dynamic version — resolve through [tool.hatch.version] path,
+              # the same source hatchling reads at build time.
+              path = pyproject.get("tool", {}).get("hatch", {}).get("version", {}).get("path")
+              if not path:
+                  fail("version is dynamic but [tool.hatch.version].path is not declared")
+              src = open(path, encoding="utf-8").read()
+              match = re.search(r'__version__\s*=\s*"([^"]+)"', src)
+              if not match:
+                  fail(f"could not resolve __version__ from {path}")
+              version = match.group(1)
+          print(f"package version: {name} == {version}")
+
+          expected = os.environ.get("EXPECTED_VERSION", "").strip()
+          if expected:
+              if version != expected:
+                  fail(f"dispatch input {expected!r} != package version {version!r}")
+              print(f"dispatch input matches package version: {version}")
+          else:
+              print("no version input supplied — input-match check skipped")
+
+          pypi_name = re.sub(r"[-_.]+", "-", name).lower()
+          url = f"https://pypi.org/pypi/{pypi_name}/json"
+          releases = None
+          try:
+              with urllib.request.urlopen(url, timeout=15) as resp:
+                  releases = json.load(resp).get("releases", {})
+          except urllib.error.HTTPError as e:
+              if e.code == 404:
+                  print(f"{pypi_name}: not on PyPI yet (HTTP 404) — first publish")
+              else:
+                  fail(f"PyPI JSON returned HTTP {e.code}; refusing to publish unverified")
+          except Exception as e:
+              fail(f"PyPI check failed: {e}")
+          if releases is not None and version in releases:
+              fail(f"{pypi_name} {version} is already published on PyPI")
+
+          if os.path.exists("CHANGELOG.md"):
+              lines = open("CHANGELOG.md", encoding="utf-8").read().splitlines()
+              tracks = any(re.match(r"##\s*\[?\d+\.\d+", l) for l in lines[:40])
+              if not tracks:
+                  print("CHANGELOG.md does not track versions — changelog gate skipped")
+              elif any(l.startswith("##") and version in l for l in lines):
+                  print(f"CHANGELOG.md has an entry for {version}")
+              else:
+                  fail(f"CHANGELOG.md tracks versions but has no entry for {version}")
+          else:
+              print("no CHANGELOG.md — changelog gate skipped")
+
+          print(f"version gate OK: {name} {version}")
+          PY
+
+      - name: Build wheel + sdist
+        run: python -m pip install --quiet build twine && python -m build
+
+      - name: Twine check
+        run: python -m twine check dist/*
+
+      - name: Inspect wheel contents
+        run: |
+          for whl in dist/*.whl; do
+            echo "== $whl"
+            python -m zipfile -l "$whl"
+          done
+
+      - name: Record artifact checksums
+        run: (cd dist && sha256sum -- *) | tee dist-checksums.txt
+
+      - name: Upload release artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: release-dist
+          path: |
+            dist/
+            dist-checksums.txt
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # configure protection rules/reviewers for the "release" environment
+    # in repo Settings > Environments
+    environment: release
+    permissions:
+      contents: read
+      id-token: write  # OIDC for PyPI trusted publishing — scoped to this job only
+    steps:
+      - name: Download release artifact
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-dist
+
+      - name: Verify artifact integrity (same artifact that was built)
+        run: |
+          test -f dist-checksums.txt
+          cd dist && sha256sum --check ../dist-checksums.txt
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  verify:
+    name: Verify published package
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Wait for release to appear on PyPI
+        env:
+          PKG_NAME: forge-agent-bridge
+          EXPECTED_VERSION: ${{ inputs.version }}
+        run: |
+          python - <<'PY'
+          import os, sys, time, urllib.request
+          name = os.environ["PKG_NAME"]
+          version = os.environ["EXPECTED_VERSION"]
+          url = f"https://pypi.org/pypi/{name}/{version}/json"
+          for attempt in range(1, 21):  # up to ~5 min
+              try:
+                  with urllib.request.urlopen(url, timeout=15) as resp:
+                      if resp.status == 200:
+                          print(f"{name} {version} live on PyPI (attempt {attempt})")
+                          sys.exit(0)
+              except Exception as e:
+                  print(f"attempt {attempt}/20: not live yet ({e})")
+              time.sleep(15)
+          sys.exit(f"{name} {version} not visible on PyPI after ~5 minutes")
+          PY
+
+      - name: Install published package in clean venv
+        run: |
+          python -m venv /tmp/verify-venv
+          for i in 1 2 3 4 5 6 7 8 9 10; do
+            if /tmp/verify-venv/bin/python -m pip install --no-cache-dir \
+              --index-url https://pypi.org/simple \
+              "forge-agent-bridge==${{ inputs.version }}"; then break; fi
+
+                echo "install attempt $i failed (index propagation); retrying in 30s"
+
+                sleep 30
+
+              done
+
+      - name: Smoke test console script
+        run: /tmp/verify-venv/bin/forge-bridge --version

forge_agent_bridge-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+graphify-out/
+.claude/
+.claude-flow/

forge_agent_bridge-0.2.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: forge-agent-bridge
+Version: 0.2.0
+Summary: Forge Agent Bridge — universal agent session/event/approval contracts and provider adapters (Claude Code, Codex, Devin)
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.6
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'

forge_agent_bridge-0.2.0/README.md

@@ -0,0 +1,238 @@
+# Forge Agent Bridge
+
+A **provider-agnostic agent session bridge** for the Forge ecosystem. One
+local HTTP surface exposes Claude Code, Codex CLI and Devin sessions through a
+single typed contract — so Forge Portal's Chat Studio (or any host) can create,
+prompt, approve, replay and hand off agent sessions without knowing provider
+CLI details.
+
+Part of the [Product Forge](https://github.com/EdgarSocrates98/product-forge)
+ecosystem. Architectural decision: [docs/adr/ADR-001-repo-and-architecture.md](docs/adr/ADR-001-repo-and-architecture.md).
+
+## What it does
+
+| Capability | How |
+|---|---|
+| **Session orchestration** | `BridgeOrchestrator` — create → prompt → drain → replay → cancel → close per provider adapter |
+| **Real provider adapters** | Claude (`stream-json` bidirectional), Codex (`exec --json` JSONL + resume), Devin (`acp` native), `fake` for tests |
+| **Local bridge service** | stdlib HTTP on `127.0.0.1` only, pairing bearer token (`0600`), process supervisor |
+| **Runner registry** | local + remote runners; remote starts `unverified`, health probe gates placement |
+| **Budgets** | scoped limits (user/workspace/product/provider/session), day/month windows, real token recording |
+| **Collaboration** | owner/observer/delegated-approver roles, visibility, comments — observers are read-only |
+| **Audit** | append-only trail for session/runner/share/budget/approval/handoff actions |
+| **Handoff** | `remote` / `provider-resume` / `context-rebuild` — never claims unverifiable continuity |
+| **File service** | path-scoped, traversal-safe list/preview/download/upload; writes are approval-gated with versioned snapshots + restore |
+| **Artifacts** | per-session artifact listing via adapters |
+| **MCP config** | `mcp_servers` on session create, passed through to providers |
+
+## Honest capability states
+
+Nothing is simulated. Every capability is a **named state**:
+
+- `ready` — verified working (binary detected + mechanism confirmed)
+- `unverified` — mechanism implemented, not yet exercised end-to-end
+- `unavailable:<reason>` — binary absent, auth missing, transport unsupported
+- `error` — last operation failed
+
+Handoff distinguishes **`provider-resume`** (verified native resume: Codex,
+Devin) from **`context-rebuild`** (reconstructed context — returns
+`continuity: "reconstructed"`, never "identical"). Remote runner placement is
+**refused** until a health probe verifies the runner.
+
+See [docs/CAPABILITY_MATRIX.md](docs/CAPABILITY_MATRIX.md) for the live matrix
+and [docs/HOMOLOGATION.md](docs/HOMOLOGATION.md) for release evidence.
+
+## Install
+
+Two routes — same contract as `productforge install` / `sparkforge-aws install`:
+
+### Bootstrap scripts (user install, no checkout dependence)
+
+| File | Route |
+|---|---|
+| `install.sh` | POSIX (Linux/macOS) |
+| `install.windows.sh` | Windows Git Bash |
+| `install.ps1` | Windows PowerShell |
+| `scripts/forge_bootstrap.py` | shared engine, driven by `forge.json` |
+
+```bash
+./install.sh            # or: install.ps1 / install.windows.sh
+./install.sh --dry-run  # plan only
+./install.sh --editable # dev mode — CLI tied to this checkout
+```
+
+The bootstrap detects Python → builds a wheel → creates a venv at
+`~/.forge/installs/forge-agent-bridge` → writes the `forge-bridge` launcher
+(`~/.local/bin` / `%USERPROFILE%\.local\bin`) → runs a `forge-bridge --version`
+smoke → registers the install under `~/.forge/installations/`.
+
+### `forge-bridge install` (guided wizard / flag path)
+
+Bare on a terminal, `forge-bridge install` runs the guided wizard:
+**scope** (`user`·`project`·`workspace`) → **profile**
+(`minimal`·`recommended`·`full`) → **components**
+(`service`·`state`·`pairing`·`providers`·`config`) → real dry-run plan →
+confirm → apply → doctor.
+
+Non-interactive for CI:
+
+```bash
+forge-bridge install --yes --scope user --profile recommended
+forge-bridge install --dry-run                    # plan JSON, nothing written
+forge-bridge install-status                     # per-check verification
+forge-bridge uninstall --yes                    # removes generated artifacts —
+                                                # NEVER pair.token/events/backups
+```
+
+Bridge-honest components (a localhost service ships no host payloads):
+
+| Component | Effect |
+|---|---|
+| `service` | verifies `forge-bridge` on PATH (`unverified` until bootstrap ran) |
+| `state` | `<root>` + `events/` + `backups/` dirs |
+| `pairing` | `<root>/pair.token` 0600 (never rotated silently) |
+| `providers` | `<root>/providers.json` — capability-matrix snapshot |
+| `config` | `<root>/config.json` — seeded limits (rate/quota/retention) |
+
+Default state root by scope: `user` → `~/.forge-bridge`,
+`project` → `./.forge-bridge`, `workspace` → `<parent>/.forge-bridge`.
+
+### Dev
+
+```bash
+python3 -m pip install -e ".[dev]"
+forge-bridge --help
+```
+
+No dependencies beyond Python 3.11+ (`typer`, `pydantic`).
+
+## Quickstart
+
+```bash
+# 1. Pair — creates ~/.forge-bridge/pair.token (0600)
+forge-bridge pair
+
+# 2. Diagnostics — providers detected, auth states
+forge-bridge doctor
+forge-bridge providers
+
+# 3. Serve the local bridge (127.0.0.1 only)
+forge-bridge serve --port 8787
+
+# 4. From any client — bearer auth, agent-session surface
+TOKEN=$(cat ~/.forge-bridge/pair.token)
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8787/status
+curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+     -d '{"provider":"claude","product_id":"payments","title":"retry analysis"}' \
+     http://127.0.0.1:8787/agent-sessions
+curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+     -d '{"text":"summarize the retry policy"}' \
+     http://127.0.0.1:8787/agent-sessions/{sid}/prompt
+curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+     -d '{"after_seq":0}' http://127.0.0.1:8787/agent-sessions/{sid}/events
+```
+
+## Provider adapters
+
+| Provider | Mechanism | Resume | Status |
+|---|---|---|---|
+| **Claude Code** | `claude -p --output-format stream-json --input-format stream-json` | context-rebuild | binary detected |
+| **Codex CLI** | `codex exec --json` (JSONL); `codex exec resume` | provider-resume | binary detected |
+| **Devin** | `devin acp` (ACP stdio JSON-RPC) | provider-resume | binary detected |
+| **fake** | in-process scripted events | — | test provider |
+
+All adapters normalize provider output into `forge/AgentBridgeEvent/v1`
+envelopes (seq, dedupe, replay buffer, unknown natives preserved in `raw`).
+
+Details: [docs/PROVIDERS.md](docs/PROVIDERS.md).
+
+## HTTP surface
+
+Auth: `Authorization: Bearer <pair.token>` on every request.
+Identity: `X-FAB-Principal` (default `local`) — self-asserted; the pair token
+is the trust boundary.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/status` | health, workspace root, running sessions |
+| GET | `/providers` | capability matrix (detected + auth states) |
+| GET | `/audit` | audit trail tail (`X-Tail` header) |
+| POST | `/sessions` | raw process spawn (`cmd` string list) |
+| DELETE | `/sessions/{id}` | terminate spawned process |
+| POST | `/agent-sessions` | create agent session (provider, product, title, mcp_servers, runner) |
+| GET | `/agent-sessions` | list live + closed sessions with metadata |
+| PATCH | `/agent-sessions/{sid}` | update metadata (title, favorite, archived, visibility, notes) |
+| DELETE | `/agent-sessions/{sid}` | close + archive session |
+| POST | `/agent-sessions/{sid}/prompt` | send prompt (text, attachments) — authz + budget gated |
+| POST | `/agent-sessions/{sid}/events` | replay events `after_seq` |
+| POST | `/agent-sessions/{sid}/cancel` | cancel in-flight turn |
+| POST | `/agent-sessions/{sid}/resume` | resume via provider `session_ref` |
+| POST | `/agent-sessions/{sid}/approve` | resolve approval (owner/delegated) |
+| POST | `/agent-sessions/{sid}/share` | set visibility/observers/delegation |
+| POST | `/agent-sessions/{sid}/comment` | append comment |
+| POST | `/agent-sessions/{sid}/handoff` | hand off (remote / provider-resume / context-rebuild) |
+| POST | `/agent-sessions/{sid}/artifacts` | list session artifacts |
+| POST | `/files/{op}` | `list` `preview` `download` `upload` `history` `restore` |
+| GET | `/runners` | list runners |
+| POST | `/runners` | register remote runner (`unverified`) |
+| POST | `/runners/{id}/health` | probe health → `ready`/`error` |
+| POST | `/runners/{id}/deregister` | remove remote runner (local refuses) |
+| GET | `/budget` | usage summary per scope |
+| POST | `/budget/limits` | set limit (scope, key, window, tokens) |
+
+Errors are typed `FAB-*` codes in `{error: {code, message}}` envelopes;
+`FORBIDDEN` → 403, `BUDGET` → 429, `NOT-FOUND` → 404, validation → 422,
+malformed JSON → 422, adapter errors → 502.
+
+Full reference: [docs/API.md](docs/API.md).
+
+## Security model
+
+- **Localhost only** — binds `127.0.0.1`, never a public interface.
+- **Pairing token** — generated `0600`, required on every request.
+- **File safety** — root-scoped resolution, `..` traversal rejected, preview
+  size cap, mutation ops require `approved: true`, versioned snapshots before
+  overwrite, restore support.
+- **Authorization** — owner-only actions on private sessions; observers
+  read-only; delegated approver can resolve approvals.
+- **Budgets** — checked *before* prompt execution; usage recorded from real
+  provider `usage.updated` events where available (else `estimated: true`).
+- **No secrets** — credentials never reach provider envs or logs.
+
+Details: [docs/SECURITY.md](docs/SECURITY.md).
+
+## Layout
+
+```
+src/forge_agent_bridge/
+  contracts.py      # 20+ typed entities, CapabilityState
+  adapter.py        # ProviderAdapter protocol + FAB-* errors
+  events.py         # forge/AgentBridgeEvent/v1 buffer + replay
+  registry.py       # declarative provider catalog + detection
+  orchestrator.py   # adapter + normalize + buffer in one API
+  local_bridge.py   # 127.0.0.1 HTTP surface (auth, routes, error mapping)
+  runners.py        # runner registry + health lifecycle
+  budgets.py        # scoped limits + usage ledger
+  collab.py         # owner/observer/delegated authz + comments
+  metadata.py       # persisted session metadata
+  files.py          # path-scoped file ops + snapshots
+  acp.py            # ACP stdio JSON-RPC client (Devin)
+  cli.py            # forge-bridge status|doctor|providers|sessions|pair|serve
+  providers/        # claude.py, codex.py, acp_adapter.py, fake.py
+tests/              # test_cycle19 … test_cycle24 (35 tests)
+docs/               # CAPABILITY_MATRIX, HOMOLOGATION, ADR-001, API, PROVIDERS, SECURITY
+```
+
+## Development
+
+```bash
+python -m pytest -q            # 35 tests
+python -m ruff check src tests # lint
+forge-bridge doctor            # environment diagnostics
+```
+
+## Consumer
+
+**Forge Portal → Chat Studio** is the primary client: three-column session
+workspace (sessions list, stream, context/files) driving every endpoint above
+through the `PfApi` bridge service.