agent-safe-runner 0.4.0__tar.gz

agent_safe_runner-0.4.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,28 @@
+name: Bug report
+description: Report a reproducible defect
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: textarea
+    attributes:
+      label: What happened?
+      description: Include the expected and observed behavior.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Reproduction
+      description: Provide the smallest safe reproduction without credentials or private data.
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Version and operating system
+    validations:
+      required: true
+  - type: checkboxes
+    attributes:
+      label: Safety check
+      options:
+        - label: I removed credentials, tokens, cookies, and private paths from this report.
+          required: true

agent_safe_runner-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install ".[dev]"
+      - run: agent-safe --version
+      - run: python -m agent_safe_runner --version
+      - run: python -m pytest -q
+      - name: Install optional MCP adapter
+        run: python -m pip install ".[mcp]"
+      - name: Test real MCP stdio client
+        run: python -m pytest tests/test_mcp.py -q

agent_safe_runner-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Publish to PyPI (requires configured Trusted Publisher); false only validates artifacts"
+        type: boolean
+        required: true
+        default: false
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+jobs:
+  test:
+    if: github.event_name == 'release' || github.ref == 'refs/heads/main'
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: python -m pip install build twine pipx
+      - run: python -m build
+      - name: Validate package metadata, contents, and release tag
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: python scripts/check_release.py dist
+      - run: python -m twine check --strict dist/*
+      - name: Verify pipx installation of the exact wheel
+        env:
+          PIPX_HOME: ${{ runner.temp }}/agent-safe-pipx
+          PIPX_BIN_DIR: ${{ runner.temp }}/agent-safe-bin
+        run: |
+          python -m pipx install --python "$(command -v python)" dist/*.whl
+          "$PIPX_BIN_DIR/agent-safe" --version
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    needs: build
+    if: github.event_name == 'release' || inputs.publish == true
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agent-safe-runner/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish verified distributions using short-lived OIDC credentials
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

agent_safe_runner-0.4.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+*.sqlite3
+*.sqlite3-*
+audit.jsonl
+*.jsonl.lock
+agent-safe-policy.json
+.venv/

agent_safe_runner-0.4.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-09-03
+
+### Added
+
+- Optional local stdio MCP interface: submit_command, get_job, list_jobs, assess_job, verify_audit.
+- Strict bounded input schemas, MCP source labels, namespaced idempotency keys, redacted errors, and per-request policy reload.
+- Read-only SQLite access for MCP inspection; approval/execution remain separate operator actions.
+- Real subprocess MCP client tests, core-only dependency checks, and optional-extra CI coverage.
+- PyPI Trusted Publishing workflow with cross-platform tests, artifact validation, pipx smoke test, and isolated OIDC publishing job.
+- MCP setup and first-time PyPI publication documentation. The workflow alone does not mean PyPI publication has completed.
+
+## [0.3.0] - 2026-09-02
+
+### Added
+
+- Pending-by-default approval, operator label, decision time/reason, and proposal source.
+- `inbox`, read-only `assess`, explicit `approve` / `deny`, and `list --approval`.
+- Transactional decision checks and redacted audit intents; audit append failure rolls back a decision.
+- Migration checklist and regression tests for approval, concurrent decisions, and old queues.
+
+### Changed
+
+- **Breaking:** execution and claims require approval as well as policy allowance.
+- Old queued/retry-wait jobs and expired running jobs require review after migration.
+- Manual retry (including dead-letter jobs) clears approval; automatic retries retain it.
+- New jobs store an absolute working directory even when `--cwd` is omitted.
+- Argument prefixes are case-sensitive; review policies that relied on case folding.
+
+### Fixed
+
+- Missing executable names no longer match each other; POSIX executable paths retain case sensitivity.
+- Execution uses the resolved executable path instead of searching again in the job directory.
+- Process-start failures release the lease and follow the bounded retry policy.
+- Workers recover expired leases even when no other queued job exists.
+- Cancellation and manual retry use conditional state updates to avoid overwriting a concurrent claim.
+
+## [0.2.1] - 2026-08-28
+
+### Added
+
+- End-user installation, upgrade, uninstall, troubleshooting, and first-run instructions.
+- `agent-safe --version` and `python -m agent_safe_runner` entry points.
+- A harmless `python --version` rule in the generated sample policy.
+
+### Changed
+
+- Package metadata now links to the Umefor Labs repository, documentation, and issue tracker.
+- CI action runtimes were updated and now include an installed-command smoke test.
+
+## [0.2.0] - 2026-08-28
+
+### Added
+
+- Deny-by-default command policy with prefixes, working roots, argument denials, and execution limits.
+- Atomic job leases, expired-lease recovery, bounded retry with backoff, cancellation, and manual retry.
+- Secret-like argument rejection, minimal child environment, output redaction, and output limits.
+- Hash-chained JSONL audit verification.
+- Structured CLI commands for policy initialization, queue inspection, execution, workers, cancellation, retry, and audit verification.
+- Migration support for databases created by `0.1.x`.
+- Cross-platform CI configuration, threat model, security policy, and contributing guide.
+
+## [0.1.0] - 2026-08-28
+
+### Added
+
+- Initial SQLite queue, idempotent submission, dry run, execution, JSONL audit, and CLI.

agent_safe_runner-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Thanks for helping improve `agent-safe-runner`.
+
+## Development setup
+
+```bash
+python -m venv .venv
+```
+
+Activate it in PowerShell on Windows:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+Or on macOS/Linux:
+
+```bash
+source .venv/bin/activate
+```
+
+Then install and test (repeat the install after changing package metadata):
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Keep runtime dependencies in the Python standard library unless a new dependency has a clear security and maintenance benefit.
+
+## Pull requests
+
+1. Open an issue before a large behavior or schema change.
+2. Add focused tests for changed behavior.
+3. Preserve deny-by-default execution and backward-compatible database migration.
+4. Do not add examples containing real credentials, tokens, cookies, or private paths.
+5. Update the README and changelog when user-facing behavior changes.
+
+Security-sensitive changes should include the threat being addressed, assumptions, failure mode, and test evidence.
+
+## Commit style
+
+Use a short imperative subject, for example `Reject secrets before persistence`. Keep unrelated changes in separate commits.

agent_safe_runner-0.4.0/LICENSE

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

agent_safe_runner-0.4.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.5
+Name: agent-safe-runner
+Version: 0.4.0
+Summary: A local-first, auditable job runner for AI-agent automation
+Project-URL: Homepage, https://github.com/umefor-labs/agent-safe-runner
+Project-URL: Documentation, https://github.com/umefor-labs/agent-safe-runner/blob/main/docs/getting-started.md
+Project-URL: Issues, https://github.com/umefor-labs/agent-safe-runner/issues
+Project-URL: Source, https://github.com/umefor-labs/agent-safe-runner
+Author: Umefor Labs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,automation,job-queue,local-first,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: jsonschema<5,>=4.20; extra == 'mcp'
+Requires-Dist: mcp<3,>=2.1; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# agent-safe-runner
+
+[![CI](https://github.com/umefor-labs/agent-safe-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/umefor-labs/agent-safe-runner/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+`agent-safe-runner` is a small, local-first queue for automation commands proposed by AI agents. It stores jobs in SQLite, requires a separate approval decision and an explicit command policy before execution, and writes a redacted JSONL audit trail.
+
+The project is intentionally narrow: it helps a local operator control which commands may run, when they may run, and what evidence is retained afterward.
+
+> [!WARNING]
+> This project is an execution gate, not an operating-system sandbox. Run workers with a low-privilege account and use containers or OS isolation for untrusted code.
+
+## Why it exists
+
+Agent workflows often grow from scripts into unattended queues. At that point, a plain `subprocess.run()` leaves important questions unanswered:
+
+- Was the command explicitly allowed?
+- Who reviewed it before execution?
+- Could two workers run the same job?
+- Did a retry happen, and why?
+- Did logs accidentally store a token?
+- Can the operator verify the event history?
+
+This runner makes those controls explicit without adding a service, broker, or cloud dependency.
+
+## Features
+
+- Deny-by-default JSON policy with command-prefix and working-directory rules
+- Approval inbox, read-only assessment, and explicit approve/deny decisions
+- Dry run by default; real execution requires approval, policy allowance, and `--execute`
+- SQLite queue with idempotency keys and fail-closed schema migration from `0.1.x` / `0.2.x`
+- Atomic leases, expired-lease recovery, bounded retries, and exponential backoff
+- Job cancellation, manual retry, status filtering, and one-pass worker mode
+- Secret-like argument rejection before persistence
+- Minimal child-process environment and redacted output capture
+- Append-only JSONL audit events with a verifiable SHA-256 hash chain
+- Structured JSON output and errors for scripting
+- Optional stdio MCP adapter with proposal/read-only tools; no approval or execution tools
+- Standard-library runtime with no required third-party dependencies
+
+## Install
+
+Python 3.11 or newer is required.
+
+Install the latest version directly from GitHub:
+
+```bash
+python -m pip install "https://github.com/umefor-labs/agent-safe-runner/archive/refs/heads/main.zip"
+```
+
+Confirm that the command is available:
+
+```bash
+agent-safe --version
+```
+
+If your system does not expose the `agent-safe` command after installation,
+use `python -m agent_safe_runner` in its place.
+
+### Short installation command (after PyPI publication)
+
+Once a release is listed on [PyPI](https://pypi.org/project/agent-safe-runner/),
+users can install it in isolation with:
+
+```bash
+pipx install agent-safe-runner
+```
+
+Until the first PyPI upload is verified, use the GitHub installation above.
+A GitHub push alone does not publish to PyPI; maintainers can follow the
+[publishing checklist](docs/publishing.md).
+
+For AI-agent integrations, see the [optional MCP adapter](docs/mcp.md).
+
+For an isolated installation with `pipx`, see the
+[getting-started guide](docs/getting-started.md). Contributors should use the
+[development setup](CONTRIBUTING.md).
+
+## Quick start
+
+Create a dedicated workspace so the queue, policy, and audit files stay together:
+
+```bash
+mkdir agent-safe-workspace
+cd agent-safe-workspace
+agent-safe init-policy
+```
+
+The generated `agent-safe-policy.json` contains a few example rules. Review it
+before use: `python --version` prints a version, but `pytest` executes project
+code and is appropriate only in a trusted workspace.
+
+Queue a command that prints the installed Python version:
+
+```bash
+agent-safe submit --cwd . --timeout 30 -- python --version
+```
+
+The command returns a JSON object. Copy its `id`, then inspect the job and perform
+a dry run. Replace `JOB_ID` below with that value:
+
+```bash
+agent-safe show JOB_ID
+agent-safe assess JOB_ID
+agent-safe run JOB_ID
+```
+
+`assess` returns `allowed`, `reason`, and `matched_rule`. An allowed job is still
+pending approval. `run` without `--execute` remains a dry run.
+
+After reviewing the exact command, directory, timeout, and retry limit, record
+your decision. Replace `local-operator` with a label meaningful to you:
+
+```bash
+agent-safe approve JOB_ID --by local-operator --reason "Reviewed version check"
+agent-safe run JOB_ID --execute --worker local-1
+```
+
+`--by` is an audit label, **not authentication**. Anyone with access to the
+approval CLI or writable database can approve jobs; this is a workflow gate.
+
+The final JSON should report `"status": "succeeded"`. Verify the audit chain's
+integrity:
+
+```bash
+agent-safe audit-verify
+```
+
+See [Getting started](docs/getting-started.md) for installation isolation,
+upgrades, troubleshooting, and a complete first-run walkthrough.
+
+## Common commands
+
+```bash
+agent-safe list
+agent-safe inbox
+agent-safe list --approval pending
+agent-safe list --status queued --status retry_wait
+agent-safe show JOB_ID
+agent-safe assess JOB_ID
+agent-safe deny JOB_ID --by local-operator --reason "Not needed"
+agent-safe cancel JOB_ID
+agent-safe retry JOB_ID
+agent-safe work --once --execute --worker local-1
+agent-safe audit-verify
+```
+
+Global paths must appear before the subcommand:
+
+```bash
+agent-safe --db /path/to/jobs.sqlite3 --audit /path/to/audit.jsonl --policy /path/to/policy.json list
+```
+
+Everything after `--` in `submit` is stored as an argument vector and is never
+passed through a shell parser. All commands emit JSON. Expected input, state, and
+policy errors return exit code `2` with a stable error code.
+
+`work --once --execute` picks only approved jobs. Manual `retry` clears the old
+decision and requires fresh approval; automatic retries keep the existing
+approval for the unchanged job. `deny` cancels a pending job. To stop an already
+approved queued job, use `cancel`.
+
+## Upgrade and uninstall
+
+**Upgrading from 0.2.x or older?** Stop all workers and back up your local state
+before installing. Old queued jobs become pending and will not run until
+reviewed. See the [0.3 migration guide](docs/migration-0.3.md).
+
+Upgrade to the latest GitHub version:
+
+```bash
+python -m pip install --upgrade "https://github.com/umefor-labs/agent-safe-runner/archive/refs/heads/main.zip"
+```
+
+Remove the command-line application:
+
+```bash
+python -m pip uninstall agent-safe-runner
+```
+
+Uninstalling does not delete your queue, policy, or audit files.
+
+## Policy
+
+Execution is denied when the policy file is absent. A policy contains:
+
+```json
+{
+  "version": 1,
+  "allowed_commands": [
+    {"program": "python", "args_prefix": ["--version"]},
+    {"program": "python", "args_prefix": ["-m", "pytest"]},
+    {"program": "git", "args_prefix": ["status"]}
+  ],
+  "allowed_working_roots": ["."],
+  "denied_arguments": ["--force", "--hard"],
+  "environment_allowlist": ["PATH", "PATHEXT", "SYSTEMROOT", "WINDIR", "TEMP", "TMP"],
+  "max_timeout_seconds": 300,
+  "max_output_chars": 8000
+}
+```
+
+Rules compare resolved executable paths and the case-sensitive beginning of the argument list. Missing executables do not match. An empty `args_prefix` allows every argument for that executable and should be used cautiously.
+
+Never place credentials in a command. The runner rejects common secret flags and token formats, but detection cannot identify every secret. Use a dedicated secret provider and grant the worker only the environment variables it needs.
+
+## Job states
+
+```text
+queued -> running -> succeeded
+                  -> retry_wait -> running
+                  -> failed
+queued/retry_wait -> cancelled -> queued (manual retry)
+queued/retry_wait -> dead_letter (policy denial)
+```
+
+Approval is separate from execution status: `pending`, `approved`, `denied`, or
+`legacy` for historical records. New jobs start `queued` + `pending`.
+Policy-invalid approved jobs become `dead_letter` without spawning a process.
+Nonzero exits, timeouts, and process-start failures retry up to `max_attempts`.
+
+## Data files
+
+- `agent-safe.sqlite3`: queue state, commands, and redacted results
+- `audit.jsonl`: redacted event records and hash-chain metadata
+- `agent-safe-policy.json`: local execution policy
+
+These runtime files are ignored by Git. SQLite commands are stored in plain text, so do not submit secrets or place the database in a public or broadly synchronized directory.
+
+## Current limits
+
+- The audit chain detects accidental edits; it is not a cryptographic signature and an attacker with write access can rebuild it.
+- Audit appends use advisory file locking on Windows and POSIX; filesystems that ignore advisory locks are unsupported for multi-process writers.
+- Running jobs cannot currently be interrupted by `cancel`; cancellation applies to queued and retry-wait jobs.
+- Approval records are not signatures or user authentication. This gate cannot constrain an agent that already has unrestricted terminal or file access.
+- SQLite state and JSONL audit are separate stores, not a single crash-atomic transaction. See [Architecture](docs/architecture.md).
+- Output limits bound stored text, not peak capture memory; lease recovery is at-least-once, not an exactly-once guarantee for external side effects.
+- MCP is local stdio only. There is no remote API, scheduler daemon, plugin system, or secret-provider integration yet.
+
+See [Architecture](docs/architecture.md), [Threat model](docs/threat-model.md), [Roadmap](ROADMAP.md), [Contributing](CONTRIBUTING.md), and [Security policy](SECURITY.md).
+
+## License
+
+MIT