agentcam 0.1.0__tar.gz

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

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install agentcam + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Show environment
+        run: |
+          python --version
+          git --version
+          agentcam version
+
+      - name: Configure git identity (needed by tmp_git_repo fixture)
+        run: |
+          git config --global user.email "ci@example.com"
+          git config --global user.name "CI"
+          git config --global commit.gpgsign false
+
+      - name: Run pytest
+        run: python -m pytest -v --maxfail=5

agentcam-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+*.egg-info/
+.venv/
+.venv*/
+venv/
+env/
+dist/
+build/
+.coverage
+.coverage.*
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+.tox/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db

agentcam-0.1.0/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+All notable changes to agentcam are recorded here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) loosely.
+Versioning follows [SemVer](https://semver.org/) once 1.0.0 ships;
+0.x is unstable on purpose.
+
+## [Unreleased]
+
+### Renamed (2026-05-16)
+
+- **Package + CLI renamed `agentbox` → `agentcam`** (PyPI name `agentbox`
+  was taken; `agentcam` is available on PyPI and free of prominent GitHub
+  collisions). Source dir `src/agentbox/` → `src/agentcam/`; CLI entry
+  `agentbox` → `agentcam`; artifact path `<git_dir>/agentbox/runs/` →
+  `<git_dir>/agentcam/runs/`. All 25 files updated; 171 tests still pass.
+- GitHub repo renamed `agent-run-flight-recorder` → `agentcam`.
+  Old URL auto-redirects via GitHub.
+
+### Hardening (post-source-review fixes, 2026-05-16)
+
+- **report.py**: `cf.rename_from` now passes through secret-like-filename
+  redaction; `git diff --check` output now passes through a new
+  `_redact_filenames_in_diff_check` helper; report `Logs` and
+  `Local Artifacts` sections show paths relative to git_root instead of
+  absolute (no longer leaks username + repo location).
+- **redaction.py**: `StreamingRedactor` now keeps a 1024-char reserve on
+  force-flush so a token straddling the SOFT_FLUSH boundary can reassemble;
+  `feed()` strips NUL bytes after decode (catches UTF-16LE / NUL-interleaved
+  output); added `URL_BASIC_AUTH` pattern to redact `https://user:pass@host`;
+  all secret-like patterns now case-insensitive.
+- **scanner.py**: secret-like basename patterns all case-insensitive
+  (catches `.ENV`, `ID_RSA`, `.NPMRC` on case-insensitive filesystems).
+- **runner.py**: `proc.wait()` wrapped in try/except KeyboardInterrupt /
+  finally — Ctrl+C now escalates wait→terminate→kill and always joins tee
+  threads (so logs flush). New `_escape_for_cmd_shim` helper caret-escapes
+  `& | < > ^` and doubles `%` for the Windows `.cmd` / `.bat` shim path.
+- **+21 regression tests** covering each fix.
+- **External confirm-review**: Codex confirmed all 9 fixes OK with NO
+  BLOCKERS (direct `codex exec`, after three attempts via the
+  `codex-rescue` subagent forwarder hung in session deadlocks).
+- **Cross-platform validation (partial)**: pytest now passes on Linux
+  (WSL Ubuntu, Python 3.12.3) too — 172/172 (POSIX signal test runs there).
+  Total coverage: Windows 171/172 + Linux 172/172. macOS still untested
+  (no local hardware; CI yaml covers it pending future GH push).
+- **POSIX risks documented for v0.2** (Codex cross-platform risk
+  assessment): SIGINT process-group leak, non-UTF8 filename decoding,
+  POSIX exec permission. See ROADMAP v0.2 "POSIX hardening" entry and
+  `docs/design.md` caveat 3.
+- **GitHub Actions matrix green (6/6 jobs)** on push to main:
+  Linux / macOS / Windows × Python 3.11 / 3.12 all pass.
+  Repo: https://github.com/shihchengwei-lab/agentcam (renamed from agent-run-flight-recorder on 2026-05-16)
+
+## [0.1.0] — 2026-05-16
+
+First release. The whole point of v0.1 is "wrap one agent run, produce a
+report, do not lie about what we don't know."
+
+### Added
+
+- **`agentcam version`** — print version and exit
+- **`agentcam run -- <argv...>`** — wrap an argv-style command, record
+  before/after git state, tee stdout/stderr, generate Markdown report
+
+#### What gets recorded per run
+
+- `stdout.log` / `stderr.log` — raw bytes from the subprocess, preserved
+  for forensic review
+- `stdout.redacted.log` / `stderr.redacted.log` — secrets stripped
+  (best-effort) via streaming buffer (handles tokens cut at chunk
+  boundaries and multi-line PEM blocks)
+- `manifest.json` — machine-readable run metadata
+- `AGENT_RUN_REPORT.md` — human-readable report
+
+All artifacts live under `<git_dir>/agentcam/runs/<run_id>/` so git itself
+cannot stage them.
+
+#### Risk heuristics in this release
+
+- **HIGH**: tracked file deletions; sensitive path segments (`auth`,
+  `login`, `oauth`, `session`, `jwt`, `permission`, `migration`, `secret`,
+  `credential`, `terraform`, `kubernetes`, `helm`, etc.); sensitive
+  basenames / extensions (`.env`, `.env.*`, `*.pem`, `*.key`, `id_rsa*`,
+  `schema.prisma`, `fly.toml`, `vercel.json`, `.tf`, `.tfvars`); GitHub
+  Actions workflow paths; output-pattern hits like `git reset --hard`,
+  `rm -rf /`, `chmod 777`, `curl ... | sh`, PowerShell
+  `Remove-Item -Recurse -Force`, `Invoke-Expression`, conflict markers,
+  `git push --force`.
+- **MEDIUM**: dependency manifest changes (`package.json`, `pyproject.toml`,
+  `Dockerfile`, etc.); output mentions of `tests failed`, `lint error`,
+  `build failed`, `panic`, `segmentation fault`.
+- No LOW level — filename-only heuristics for "trivial" changes are
+  unreliable.
+
+#### Redaction
+
+- Streaming redactor handles tokens split across read chunks and PEM
+  blocks split across multiple lines (PKCS#8 / RSA / EC / ED25519 /
+  ENCRYPTED / OPENSSH).
+- Secret-like filenames (`.env`, `*.pem`, `id_rsa`, `*credential*`,
+  `*secret*`) are redacted in every Markdown surface (Changed Files, Risk
+  Flags evidence, Diff Stat, Rollback Notes, Command field).
+- Argv redaction also runs on each argv element (catches
+  `--api-key sk-...` and `--config .env.production`).
+
+#### Exit code
+
+- Wrapper exits `0` iff subprocess returncode is `0`, `1` otherwise.
+- Original returncode, platform, and a human interpretation (POSIX signal
+  name; common Windows NTSTATUS like `STATUS_ACCESS_VIOLATION`) all go to
+  `manifest.exit_detail` and the `Exit Code Detail` report section.
+- Run-id collision (same millisecond, same slug, all hex retries
+  exhausted) exits with `2` — distinct from "subprocess failed" `1`.
+
+### Tests
+
+- 159 unit + e2e tests across 8 test modules
+- Cross-platform: passes on Windows (POSIX-only signal test skipped)
+- e2e suite uses real subprocesses + real git repos via
+  `tmp_git_repo` fixture
+- Regression guards for every blocker found during two rounds of Codex
+  adversarial review (PEM cross-chunk, exit-code 256-not-zero, segment vs.
+  substring matching, staged-only diff visible, output evidence does not
+  echo raw matched text, etc.)
+
+### Documentation
+
+- `README.md` — quick start, install, threat model, known limitations,
+  hacking
+- `docs/design.md` — 22 decisions in "decision / why / why not" format
+- `examples/risky-auth-change/` — one committed sample report and scenario
+  description
+- `SECURITY.md` — vulnerability disclosure policy, scope, threat model
+
+### Known limitations (v0.1)
+
+- Not a sandbox; not a pre-execution gate; not a compliance product.
+- Best-effort redaction; new secret formats may slip through.
+- No interactive TUI rendering guarantee.
+- No submodule / sparse-checkout special handling.
+- Windows console encoding fallback may degrade live terminal display
+  (raw log on disk is unaffected).
+- `Tests / Build / Lint observed` always reports `unknown` — heuristic
+  detection deferred to a future release.
+
+### Out of scope (deliberately, see `docs/design.md` "Out-of-scope reminders")
+
+- Sandbox / process isolation
+- Pre-execution blocking / approval gating
+- Auto-rollback / `git clean -fd` suggestions
+- Cloud upload / telemetry of any kind
+- VS Code / IDE integration
+- GitHub App / GitHub Action (deferred to v0.2 if v0.1 finds users)
+- Custom YAML risk rules
+- Multi-run dashboard
+- Hosted SaaS dashboard

agentcam-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shihchengwei
+
+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.

agentcam-0.1.0/PKG-INFO

@@ -0,0 +1,313 @@
+Metadata-Version: 2.4
+Name: agentcam
+Version: 0.1.0
+Summary: Local-first CLI wrapper that records what your AI coding agent changed in your repo.
+Author-email: shihchengwei <shihchengwei@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,coding-agent,flight-recorder,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentcam
+
+[![CI](https://github.com/shihchengwei-lab/agentcam/actions/workflows/ci.yml/badge.svg)](https://github.com/shihchengwei-lab/agentcam/actions/workflows/ci.yml)
+
+> Local-first CLI wrapper that records what your AI coding agent changed in your repo and generates a Markdown run report after each run.
+
+agentcam does **not** replace Claude Code, Codex, OpenHands, Aider, or any
+other coding agent. It wraps them.
+
+```bash
+agentcam run -- claude "fix the failing tests"
+agentcam run -- codex "add input validation to login form"
+agentcam run -- bash -lc "npm run build && npm test"
+```
+
+After each run, you get an `AGENT_RUN_REPORT.md` answering three questions:
+
+1. **What did the agent change?** — exact file list, diff stat, staged vs.
+   unstaged vs. untracked, before/after HEAD.
+2. **Where should I look first?** — heuristic risk flags for auth paths,
+   secrets, deletions, dangerous shell strings (`rm -rf /`, `git reset
+   --hard`, conflict markers), dependency manifests.
+3. **How do I roll back if something's wrong?** — situation-aware rollback
+   notes (no blanket `git reset --hard` suggestions).
+
+See [`examples/risky-auth-change/expected-report.md`](examples/risky-auth-change/expected-report.md)
+for what a report looks like when the agent touches a sensitive area.
+
+---
+
+## What this is NOT
+
+This is a **flight recorder**, not a governance platform.
+
+- Not a sandbox.
+- Not a pre-execution gate. agentcam does not block dangerous commands; it
+  records that they happened and flags them for review *after*.
+- Not a security scanner. The risk flags are heuristics ("look here"), not
+  verdicts ("this is bad").
+- Not an audit / compliance tool. The Markdown report is for the developer
+  reviewing the diff, not for a SOC2 evidence pipeline.
+- Not a SaaS. There is no account, no upload, no telemetry. Everything
+  stays under `.git/agentcam/runs/` on your machine.
+
+---
+
+## Install
+
+agentcam needs Python ≥ 3.11 and `git`.
+
+```bash
+pipx install agentcam
+```
+
+(Once published to PyPI. For now, install from source — see "Hacking"
+below.)
+
+Verify:
+
+```bash
+agentcam version
+# agentcam 0.1.0
+```
+
+---
+
+## Quick start
+
+Inside any git repository:
+
+```bash
+agentcam run -- bash -lc "echo hello > demo.txt"
+```
+
+agentcam will:
+
+1. snapshot git state (HEAD, branch, staged / unstaged / untracked)
+2. run your command, tee-ing stdout and stderr to logs (raw + redacted)
+3. snapshot git state again
+4. scan for risk flags (path patterns, output patterns, deletions)
+5. write `AGENT_RUN_REPORT.md` and `manifest.json` under
+   `.git/agentcam/runs/<run_id>/`
+6. exit with 0 if your command succeeded, 1 otherwise
+
+stdout and stderr stream live to your terminal — agentcam does not buffer
+them.
+
+### Wrapping Claude Code
+
+```bash
+agentcam run --name claude-fix-tests -- claude "fix the failing tests"
+```
+
+### Wrapping Codex
+
+```bash
+agentcam run --name codex-add-validation -- codex "add input validation to login form"
+```
+
+### Wrapping anything (with shell features)
+
+agentcam runs the command with `shell=False`. If you need pipes, redirects,
+variable expansion, wrap your own shell explicitly:
+
+```bash
+agentcam run -- bash -lc "npm run build 2>&1 | tee build.log"
+agentcam run -- pwsh -Command "Get-Process | Out-File procs.txt"
+agentcam run -- cmd /c "dir > files.txt"
+```
+
+This is a deliberate constraint — see [`docs/design.md` § 4](docs/design.md).
+
+---
+
+## Where the artifacts live
+
+```
+.git/
+└── agentcam/
+    └── runs/
+        └── 20260516-143000-451-claude-rate-limit-login/
+            ├── AGENT_RUN_REPORT.md       # human-readable, share-friendly
+            ├── manifest.json             # machine-readable
+            ├── stdout.log                # raw stdout (KEEP PRIVATE)
+            ├── stderr.log                # raw stderr (KEEP PRIVATE)
+            ├── stdout.redacted.log       # secrets stripped (best-effort)
+            └── stderr.redacted.log
+```
+
+Output lives under `.git/` on purpose — git doesn't track its own
+internals, so agent invocations of `git add .` cannot stage agentcam's
+output by accident.
+
+> **Warning about raw logs.** Raw logs preserve the original stdout /
+> stderr for forensic review. They will *not* be picked up by `git push`,
+> but they *will* travel with `.git/` if you:
+>
+> - sync your repo via OneDrive / Dropbox / iCloud Drive
+> - back up your machine (Time Machine, Windows File History)
+> - zip the entire repo to share with someone
+>
+> The `AGENT_RUN_REPORT.md` only links to the redacted logs.
+
+---
+
+## Risk flags (heuristics)
+
+Two levels: **HIGH** and **MEDIUM**. There is no LOW — filename-only
+heuristics for "trivial" changes are unreliable, and we don't pretend.
+
+**HIGH** — flagged for any of:
+
+- A tracked file was deleted.
+- File path contains a sensitive segment: `auth`, `login`, `oauth`,
+  `session`, `jwt`, `permission`, `middleware`, `migration`, `secret`,
+  `credential`, `terraform`, `kubernetes`, `helm`, etc.
+- Sensitive basename / extension: `.env`, `.env.*`, `*.pem`, `*.key`,
+  `id_rsa*`, `schema.prisma`, `fly.toml`, `vercel.json`, `.tf`, `.tfvars`,
+  GitHub Actions workflows.
+- stdout / stderr contains a high-risk command pattern:
+  `git reset --hard`, `rm -rf /...`, `chmod 777`, `curl ... | sh`,
+  PowerShell `Remove-Item -Recurse -Force ...`, `Invoke-Expression`,
+  conflict markers, `git push --force`.
+
+**MEDIUM** — flagged for any of:
+
+- Dependency manifest changed: `package.json`, `pyproject.toml`,
+  `requirements.txt`, `Dockerfile`, `docker-compose.*`, etc.
+- stdout / stderr mentions `tests failed`, `lint error`, `build failed`,
+  `panic`, `segmentation fault`.
+
+**Path matching is segment-based.** Segment `auth` matches
+`src/auth/login.py` and `auth.ts`, but does NOT match `author.md` or
+`authorization-docs/x.md`. See [`docs/design.md` § 7](docs/design.md).
+
+**Evidence never includes raw matched text.** Risk Flags cite the pattern
+name and a line number (`stdout.log line 42`), never the matched
+substring. Secrets that happen to land near a risk pattern in output do
+not leak through the report.
+
+For the full rule list and rationale, see
+[`docs/design.md` § 7, § 12, § 15](docs/design.md).
+
+---
+
+## Secret redaction (best-effort)
+
+Patterns redacted in the redacted log:
+
+- AWS access / secret keys (`AKIA…`, `aws_secret_access_key=…`)
+- GitHub PAT (`ghp_…`, `gho_…`, etc.)
+- OpenAI / Anthropic-shaped API keys (`sk-…`)
+- Slack tokens (`xoxa-…`, `xoxb-…`, etc.)
+- npm / GitLab tokens (`npm_…`, `glpat-…`)
+- JWT (`eyJ…`)
+- `Bearer …` headers
+- env-style assignments where the key name looks like a secret
+  (`OPENAI_API_KEY=…`, `*_TOKEN=…`, `*_PASSWORD=…`, `*_CREDENTIAL=…`)
+- PEM private key blocks — multi-line, including PKCS#8 / RSA / EC /
+  ED25519 / OPENSSH
+
+We **do not** promise to catch every secret. New token formats appear all
+the time. The raw log on disk is the forensic backstop: if redaction
+missed something, you can find it there.
+
+`Command:` field, `Changed Files`, `Diff Stat`, and `Risk Flags evidence`
+in the markdown report also pass through redaction — a literal
+`.env.production` in argv or in a diff stat shows up as
+`<redacted-secret-filename>`.
+
+---
+
+## Local-only, no telemetry
+
+agentcam makes no network calls. It does not phone home. There is no
+account, no upload, no opt-in or opt-out toggle for telemetry — because
+there is no telemetry to toggle.
+
+If you ever observe an outbound connection from agentcam, that's a bug;
+please file an issue.
+
+---
+
+## Known limitations
+
+- **Not a sandbox.** agentcam does not isolate the wrapped command from
+  your filesystem, network, or credentials.
+- **Does not block.** High-risk patterns are recorded *after* they happen;
+  agentcam does not approve or deny commands.
+- **Does not see inside the agent.** agentcam observes only what reaches
+  stdout / stderr and what changes in the git working tree. The agent's
+  internal tool calls (file reads, web requests, model calls) are
+  invisible.
+- **Best-effort redaction.** New secret formats may slip through. Do not
+  rely on agentcam alone for credential hygiene.
+- **No interactive TUI guarantee.** Agents that draw full-screen TUIs
+  (curses-style) may render imperfectly through the wrapper. Their
+  side-effects on the repo are still recorded correctly.
+- **No submodule traversal.** Running inside a submodule treats it as an
+  independent repo. Superproject context is not analyzed.
+- **No sparse-checkout special handling.** Reports reflect what
+  `git status --porcelain=v1 -z` shows.
+- **Windows console encoding can degrade live terminal display.** Raw
+  bytes are always preserved on disk; only the live forwarding to the
+  terminal may fall back to UTF-8 lossy decode (recorded as
+  `terminal_forward_degraded` in the manifest).
+
+For the full list of "things we deliberately did NOT do," see the
+"Out-of-scope reminders" at the bottom of [`docs/design.md`](docs/design.md).
+
+---
+
+## Hacking
+
+```bash
+git clone <this repo>
+cd flight_recorder
+python -m venv .venv
+
+# Windows (Git Bash / PowerShell)
+.venv/Scripts/python -m pip install -e ".[dev]"
+.venv/Scripts/python -m pytest
+
+# macOS / Linux
+.venv/bin/python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest
+```
+
+The codebase is intentionally small (one source module per concern):
+
+```
+src/agentcam/
+├── cli.py          # argparse + orchestrator
+├── runner.py       # threads-based tee + exit code interpretation
+├── git_state.py    # porcelain parser + git_dir resolver
+├── paths.py        # run_id + collision-safe directory creation
+├── redaction.py    # streaming secret redactor
+├── scanner.py      # path + output risk patterns
+├── report.py       # AGENT_RUN_REPORT.md generator
+└── models.py       # dataclass definitions
+```
+
+Read [`docs/design.md`](docs/design.md) before changing anything — it
+records why each module is shaped the way it is, including the "we
+considered X and rejected it because Y" cases.
+
+---
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).