agent-saga 0.1.0__tar.gz

agent_saga-0.1.0/.claude/settings.local.json

@@ -0,0 +1,61 @@
+{
+  "permissions": {
+    "allow": [
+      "PowerShell(python --version)",
+      "PowerShell(python -c \"import sys; print\\(sys.executable\\)\")",
+      "PowerShell(cd \"D:\\\\AI Error\"; \\(Get-Content bench/results.json -Raw | ConvertFrom-Json\\).concurrency | Select-Object concurrency, total_ops, fsync_barriers, amortization, ops_per_sec | Format-Table -AutoSize)",
+      "PowerShell(cd \"D:\\\\AI Error\"; python bench/bench_core.py --samples 10000 2>&1 | Select-Object -Last 26; \\(Get-Content bench/results.json -Raw | ConvertFrom-Json\\).concurrency | Select-Object concurrency, total_ops, fsyncs, group_commit_factor, ops_per_sec, p99_ms | Format-Table -AutoSize)",
+      "PowerShell(cd \"D:\\\\AI Error\"; python -m pytest -q 2>&1 | Select-Object -Last 8; python examples/demo.py 2>&1 | Select-String -Pattern \"charge \\\\$2,500|allowed|BLOCK|no-large\" | Select-Object -First 5)",
+      "Bash(python -m pytest -q)",
+      "Bash(python -c ' *)",
+      "PowerShell(cd \"D:\\\\AI Error\"; python -m pytest -q 2>&1 | Select-Object -Last 4; echo \"EXIT: $LASTEXITCODE\")",
+      "PowerShell(cd \"D:\\\\AI Error\"; python -m pytest -q 2>&1 | Select-Object -Last 3; echo \"EXIT: $LASTEXITCODE\")",
+      "PowerShell(cd \"D:\\\\AI Error\"; python -m pytest tests/test_ui.py -q 2>&1 | Select-Object -Last 3; echo \"EXIT: $LASTEXITCODE\")",
+      "PowerShell(cd \"D:\\\\AI Error\"; $env:PYTHONTRACEMALLOC=25; python -m pytest tests/test_ui.py::test_http_endpoints_serve_dashboard_and_api -W error 2>&1 | Select-String -Pattern \"test_ui.py:|http|client|socket\\\\.py|urlopen\" | Select-Object -First 12; $env:PYTHONTRACEMALLOC=\"\")",
+      "Bash(python -m agent_saga.cli ui --wal-path ./demo-agent-saga.wal --port 8137)",
+      "Bash(curl -s http://127.0.0.1:8137/api/sagas)",
+      "Bash(python -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\('sagas:', d['total']\\); [print\\(' ', s['status'], s['step_count'],'steps', round\\(s['total_latency_ms'],2\\),'ms'\\) for s in d['sagas']]\")",
+      "Bash(netstat -ano)",
+      "Bash(python -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\('sagas:', d['total']\\); [print\\(' ', s['status'], '|', s['step_count'],'steps |', round\\(s['total_latency_ms'] or 0,2\\),'ms'\\) for s in d['sagas']]\")",
+      "Bash(rm -f demo-agent-saga.wal)",
+      "Bash(python -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\('sagas:', d['total']\\); [print\\(' ', s['status'].ljust\\(12\\), '|', s['step_count'],'steps'\\) for s in d['sagas']]\")",
+      "Bash(taskkill //F //FI \"WINDOWTITLE eq *\" //IM python.exe)",
+      "PowerShell($c = Get-NetTCPConnection -LocalPort 8137 -State Listen -ErrorAction SilentlyContinue; if \\($c\\) { Stop-Process -Id $c.OwningProcess -Force; \"stopped PID $\\($c.OwningProcess\\)\" } else { \"no listener on 8137\" })",
+      "PowerShell(cd \"D:\\\\AI Error\"; python -m pytest -q 2>&1 | Select-Object -Last 6; echo \"EXIT: $LASTEXITCODE\")",
+      "Bash(python -m agent_saga.ui --wal-path ./demo-agent-saga.wal --port 8138)",
+      "Read(//tmp/**)",
+      "Bash(curl -s http://127.0.0.1:8138/api/sagas)",
+      "Bash(python -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\('sagas:', d['total']\\)\")",
+      "PowerShell($c = Get-NetTCPConnection -LocalPort 8138 -State Listen -ErrorAction SilentlyContinue; if \\($c\\) { Stop-Process -Id $c.OwningProcess -Force; \"stopped $\\($c.OwningProcess\\)\" }; cd \"D:\\\\AI Error\"; python -m pytest -q 2>&1 | Select-Object -Last 2)",
+      "Bash(git --no-pager log --oneline -8)",
+      "Bash(curl -fsSL https://www.gnu.org/licenses/agpl-3.0.txt -o LICENSE)",
+      "Bash(curl -fsSL --ssl-no-revoke https://www.gnu.org/licenses/agpl-3.0.txt -o LICENSE)",
+      "Bash(git add *)",
+      "Bash(git -c user.name=Thomas -c user.email=dev@agentrollback.io commit -q -m 'License under AGPL-3.0-only with a commercial exemption *)",
+      "Bash(git --no-pager log --oneline -3)",
+      "Bash(git -c user.name=Thomas -c user.email=dev@avertis.systems commit -q -m 'Attribute the project to Avertis Systems in package metadata *)",
+      "Bash(git --no-pager log --oneline -1)",
+      "Bash(git -c user.name=Thomas -c user.email=dev@avertis.systems commit -q -m 'Snapshot-based REVERSIBLE steps *)",
+      "Bash(git push *)",
+      "Bash(git rev-list *)",
+      "Bash(git -c user.name=Thomas -c user.email=dev@avertis.systems commit -q -m 'Durable-target snapshots and CrewAI / OpenAI Agents SDK adapters *)",
+      "Bash(curl -fsSL --ssl-no-revoke \"https://api.github.com/repos/thomasjgeorge23/AI-Error/actions/runs?per_page=5\")",
+      "Bash(python -c 'import sys,json; d=json.load\\(sys.stdin\\); print\\('\\\\''total:'\\\\'', d.get\\('\\\\''total_count'\\\\''\\)\\); *)",
+      "Bash(curl -s --ssl-no-revoke \"https://api.github.com/repos/thomasjgeorge23/AI-Error/actions/runs?per_page=3\")",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" --ssl-no-revoke \"https://api.github.com/repos/thomasjgeorge23/AI-Error\")",
+      "Bash(git -c user.name=Thomas -c user.email=dev@sagaops.dev commit -q -m 'Rename to SagaOps; snapshot GC; fix 3 audit safety bugs; OSS infra *)",
+      "Bash(python -m pip install --quiet \"cryptography>=41.0\")",
+      "Bash(python -c \"from cryptography.fernet import Fernet; print\\('cryptography OK'\\)\")",
+      "Bash(git -c user.name=Thomas -c user.email=dev@sagaops.dev commit -q -m 'BYOK WAL encryption, injectable recovery lock, full-CRUD Postgres *)",
+      "Skill(artifact-design)",
+      "Skill(artifact-design:*)",
+      "Bash(git -c user.name=Thomas -c user.email=dev@sagaops.dev commit -q -m 'Launch materials: sagaops.dev landing page and Show HN kit *)",
+      "Bash(git -c user.name=Thomas -c user.email=dev@sagaops.dev commit -q -m 'LlamaIndex + AutoGen adapters, and debugger UI token auth *)",
+      "Bash(git ls-remote *)",
+      "Bash(python -)",
+      "Bash(python -m pip install --quiet --upgrade build twine)",
+      "Bash(rm -rf dist build *.egg-info)",
+      "Bash(python -m build)"
+    ]
+  }
+}

agent_saga-0.1.0/.github/workflows/bench.yml

@@ -0,0 +1,106 @@
+name: benchmark
+
+# The durable-path p99 is the number a bank's architect asks about first.
+# It cannot be measured on a developer laptop -- NTFS fsync tails on Windows
+# varied 22-33ms p99 and 40-202ms max across identical runs. This workflow
+# produces the number we are willing to publish.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      samples:
+        description: Samples per profile
+        default: "10000"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install pytest langchain-core
+      - run: python -m pytest -q
+
+  bench:
+    runs-on: ubuntu-latest
+    needs: test
+    strategy:
+      fail-fast: false
+      matrix:
+        # Three runs of each so we report median-of-p99 rather than whichever
+        # single run happened to look best. One sample of a tail is not a
+        # measurement.
+        run: [1, 2, 3]
+        gc: [enabled, disabled]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Record hardware and filesystem
+        run: |
+          echo "## runner" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          lscpu | grep -E 'Model name|^CPU\(s\)|MHz' >> $GITHUB_STEP_SUMMARY || true
+          df -hT . >> $GITHUB_STEP_SUMMARY
+          # fsync cost is a property of the device, not of our code. Capture it
+          # so the durable-path number can be read in context.
+          lsblk -d -o NAME,ROTA,MODEL >> $GITHUB_STEP_SUMMARY || true
+          echo '```' >> $GITHUB_STEP_SUMMARY
+
+      - name: Baseline fsync cost of this runner
+        run: |
+          python - <<'PY'
+          import os, statistics, tempfile, time
+          with tempfile.TemporaryDirectory() as d:
+              p = os.path.join(d, "probe")
+              fh = open(p, "w")
+              lat = []
+              for _ in range(2000):
+                  fh.write("x" * 200 + "\n"); fh.flush()
+                  t0 = time.perf_counter_ns(); os.fsync(fh.fileno())
+                  lat.append(time.perf_counter_ns() - t0)
+              fh.close()
+              s = sorted(lat)
+              print(f"raw fsync p50={s[1000]/1e6:.4f}ms p95={s[1900]/1e6:.4f}ms "
+                    f"p99={s[1980]/1e6:.4f}ms max={s[-1]/1e6:.3f}ms")
+          PY
+
+      - name: Run benchmark
+        run: |
+          python bench/bench_core.py \
+            --samples ${{ github.event.inputs.samples || 10000 }} \
+            --label ${{ matrix.gc }}-${{ matrix.run }} \
+            ${{ matrix.gc == 'disabled' && '--no-gc' || '' }} \
+            | tee bench-output.txt
+          {
+            echo "## bench (gc ${{ matrix.gc }}, run ${{ matrix.run }})"
+            echo '```'
+            cat bench-output.txt
+            echo '```'
+          } >> $GITHUB_STEP_SUMMARY
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: results-${{ matrix.gc }}-${{ matrix.run }}
+          path: bench/results-*.json
+
+  report:
+    runs-on: ubuntu-latest
+    needs: bench
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+      - name: Median-of-runs summary
+        run: python bench/summarize.py artifacts >> $GITHUB_STEP_SUMMARY

agent_saga-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+bench/results-*.json
+*.jsonl
+*.wal
+.claims/
+.venv/

agent_saga-0.1.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "agent_saga"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

agent_saga-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to agent-saga
+
+Thanks for considering a contribution. This library guards the transaction path
+of autonomous agents, so the bar is correctness first, then clarity, then speed.
+
+## Development setup
+
+```bash
+git clone <repo> && cd <repo>
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+The core suite runs with **only `pytest`** — no network, no live database, no
+real credentials. Connector and adapter tests use in-process fakes; the handful
+of real-SDK integration tests `importorskip` their framework and are skipped
+when it is absent. A contribution should keep the base suite dependency-free.
+
+## Principles this codebase holds to
+
+- **"Undo" is typed.** Every effect is `REVERSIBLE`, `COMPENSABLE`, or
+  `IRREVERSIBLE`. If you cannot say which, you do not yet understand the effect.
+- **Fail closed, and say so.** When something cannot be undone, it is reported
+  (`ORPHANED`, `NEEDS_HUMAN`), never silently dropped. Tests assert on what the
+  system *refuses* to do as much as what it does.
+- **Write-ahead, then act.** Durable intent is recorded before a side effect,
+  not after.
+- **Credentials are references, never values.** Anything that could put a secret
+  in the WAL must go through a `*_ref` and `resolve_credential`.
+- **Comments explain *why*, at the altitude of the surrounding code.** Skip
+  narration of what the line plainly does.
+
+## Adding a connector
+
+A connector is the real product surface, so it carries the most responsibility:
+
+1. Pick the correct semantics and justify it in the module docstring (a shared
+   database row is `COMPENSABLE`, not `REVERSIBLE` — see `connectors/postgres.py`
+   for why).
+2. Register the compensation handler by **name** via `@compensator`, with
+   JSON-serializable kwargs, so `saga-recoveryd` can run it after a crash.
+3. Derive the inverse at runtime from the forward result, and guard against
+   clobbering a concurrent external change.
+4. Run `assert_no_secrets` on the compensation kwargs.
+5. Test rollback, the `UNKNOWN` (timed-out) outcome, and the concurrency guard —
+   all against a fake, no live system.
+
+## Pull requests
+
+- Keep the diff focused; one concern per PR.
+- Add or update tests for the behavior you change. New behavior without a test
+  that would fail without it will be asked for one.
+- Match the surrounding style; do not reformat unrelated code.
+- Note any effect on the durability/latency story in the description.
+
+## Reporting security issues
+
+Not here — see [SECURITY.md](SECURITY.md) for the private channel.