openmuse-agent 0.3.0a0__tar.gz

openmuse_agent-0.3.0a0/.devcontainer/devcontainer.json

@@ -0,0 +1,6 @@
+{
+  "name": "OpenMuse demo",
+  "image": "mcr.microsoft.com/devcontainers/python:3.12",
+  "postCreateCommand": "pip install -e '.[dev]'",
+  "postStartCommand": "printf '\nOpenMuse is ready. Run: python examples/e2e_demo.py\nThen verify: python examples/verify_audit.py\n'"
+}

openmuse_agent-0.3.0a0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,11 @@
+name: Bug report
+description: Report a reproducible defect
+body:
+  - type: textarea
+    attributes: {label: What happened?}
+    validations: {required: true}
+  - type: textarea
+    attributes: {label: Reproduction steps}
+    validations: {required: true}
+  - type: input
+    attributes: {label: OpenMuse and Python versions}

openmuse_agent-0.3.0a0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/tahodev/openmuse/security/advisories/new
+    about: Report vulnerabilities privately, not in a public issue.

openmuse_agent-0.3.0a0/.github/ISSUE_TEMPLATE/connector.yml

@@ -0,0 +1,12 @@
+name: Connector proposal
+description: Propose a least-privilege integration
+body:
+  - type: input
+    attributes: {label: Service and use case}
+    validations: {required: true}
+  - type: textarea
+    attributes: {label: Required scopes and data flow}
+    validations: {required: true}
+  - type: textarea
+    attributes: {label: Risks, revocation, and simulation mode}
+    validations: {required: true}

openmuse_agent-0.3.0a0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,12 @@
+name: Feature request
+description: Propose a focused improvement
+body:
+  - type: textarea
+    attributes: {label: Problem, description: What user problem should this solve?}
+    validations: {required: true}
+  - type: textarea
+    attributes: {label: Proposed behavior}
+    validations: {required: true}
+  - type: textarea
+    attributes: {label: Trust-boundary impact, description: Note new data, permissions, side effects, or say none.}
+    validations: {required: true}

openmuse_agent-0.3.0a0/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule: {interval: weekly}
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: {interval: weekly}

openmuse_agent-0.3.0a0/.github/pull_request_template.md

@@ -0,0 +1,9 @@
+## What changed
+## Why
+## Trust-boundary impact
+- [ ] No change
+- [ ] Documented and tested
+## Checklist
+- [ ] Tests added/updated
+- [ ] Docs updated
+- [ ] `ruff check`, `pytest`, and `python -m build` pass

openmuse_agent-0.3.0a0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+on: [push, pull_request]
+permissions: {contents: read}
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy: {matrix: {python-version: ['3.11','3.12','3.13']}}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with: {python-version: '${{ matrix.python-version }}'}
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check src tests
+      - run: mypy src/openmuse
+      - run: pytest --cov=openmuse --cov-report=term-missing --cov-fail-under=85
+      - run: python examples/e2e_demo.py --auto-approve
+      - run: python examples/verify_audit.py
+      - run: python -m build
+      - run: python -m pip install --force-reinstall dist/*.whl
+      - run: python -c "import importlib.metadata, openmuse; assert openmuse.__version__ == importlib.metadata.version('openmuse-agent')"

openmuse_agent-0.3.0a0/.github/workflows/codeql.yml

@@ -0,0 +1,19 @@
+name: CodeQL
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '17 4 * * 1'
+permissions:
+  contents: read
+  security-events: write
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: github/codeql-action/init@c20e34f438d671fc35777cc9820dd7adf8252874 # v3
+        with: {languages: python}
+      - uses: github/codeql-action/analyze@c20e34f438d671fc35777cc9820dd7adf8252874 # v3

openmuse_agent-0.3.0a0/.github/workflows/dependency-review.yml

@@ -0,0 +1,10 @@
+name: Dependency review
+on: [pull_request]
+permissions:
+  contents: read
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4

openmuse_agent-0.3.0a0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Release
+on:
+  push:
+    tags: ['v*']
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with: {python-version: '3.12'}
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with: {name: dist, path: dist/}
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

openmuse_agent-0.3.0a0/.github/workflows/security.yml

@@ -0,0 +1,18 @@
+name: Python security checks
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '41 4 * * 2'
+permissions: {contents: read}
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with: {python-version: '3.12'}
+      - run: python -m pip install -e . pip-audit
+      - run: pip-audit

openmuse_agent-0.3.0a0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+.pytest_cache/
+.venv/
+dist/
+.openmuse/
+*.py[cod]
+.coverage
+coverage.json
+htmlcov/
+build/
+*.egg-info/

openmuse_agent-0.3.0a0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes are recorded here. OpenMuse follows semantic versioning while using prerelease tags for alpha builds.
+
+## Unreleased
+
+## v0.3.0-alpha - 2026-09-19
+
+### Added
+
+- Managed Google OAuth with authorization-code exchange, automatic refresh, encrypted token storage, and OS-keyring-backed master keys.
+- Read-only Gmail and Google Calendar connectors built on scoped, least-privilege grants, plus credential-free local simulation connectors.
+- Searchable and editable working/curated memory with hash-chained remember, promote, edit, and forget events, plus state verification against the audit chain.
+- Five-field cron scheduling with atomic job claims across workers, and subagent grants that can only narrow tools, budgets, expiry, and argument constraints.
+- A secrets broker that passes named secrets to tools through a scoped execution side channel without exposing plaintext to planner context, manifests, action arguments, or audit logs.
+- A fresh-process isolated worker with bounded runtime, memory, file descriptors, output, environment, and workspace.
+- An independent security-review packet with a reviewer brief and checklist.
+
+### Changed
+
+- The approval demo now shows the exact tool, path, content preview, and SHA-256 being approved, then verifies that the approved action is the action executed.
+- Connector revocation now clears cached clients and fails closed if cleanup does not complete.
+- Tool arguments are validated before approval, policy checks, and execution.
+- `FetchURL` now resolves once and pins connections to validated public addresses to prevent DNS-rebinding bypasses.
+- Project metadata and runtime version are aligned for this prerelease.
+
+### Fixed
+
+- Approval tokens are consumed atomically, preventing concurrent verification from using one approval twice.
+- Approval expiry now rejects tokens at the exact expiry boundary (`now >= exp`).
+- Scheduled jobs are claimed transactionally so parallel workers cannot run the same job twice.
+
+### Known limitations
+
+- OpenMuse remains alpha software for test accounts and non-sensitive data. Documentation drift in the security limits is being cleaned up separately.

openmuse_agent-0.3.0a0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use OpenMuse in research, please cite this software."
+title: "OpenMuse"
+type: software
+authors:
+  - name: "tahodev"
+repository-code: "https://github.com/tahodev/openmuse"
+license: MIT
+version: 0.3.0-alpha
+date-released: 2026-09-19

openmuse_agent-0.3.0a0/CODE_OF_CONDUCT.md

@@ -0,0 +1,2 @@
+# Code of Conduct
+We follow the [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Be respectful, assume good intent, and avoid harassment. Report conduct concerns privately through a GitHub security advisory; maintainers will review them promptly and confidentially.

openmuse_agent-0.3.0a0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+## Set up
+
+1. Fork the repository and branch from `main`.
+2. Use Python 3.11 or newer.
+3. Run `python -m venv .venv`, activate it, then `pip install -e '.[dev]'`.
+4. Before opening a pull request, run:
+
+```bash
+ruff check src tests
+mypy src/openmuse
+pytest --cov=openmuse --cov-fail-under=85
+python examples/e2e_demo.py --auto-approve
+python examples/verify_audit.py
+python -m build
+```
+
+## Changes to trust boundaries
+
+Open an issue before changing the permission model, approvals, audit format, connector scopes, data retention, or secret handling. Describe assets, attackers, failure modes, revocation, simulation behavior, and the tests that prove fail-closed behavior. Changes to these boundaries need an ADR in `docs/adr/`, threat-model updates, tests, and maintainer approval.
+
+## Connectors
+
+Start read-only, request the smallest scopes, document data flow and deletion/revocation, support simulation where possible, and never put credentials or private payloads in fixtures, logs, or issues.
+
+## Pull requests
+
+Keep changes small. Explain the user-visible behavior, trust-boundary impact, compatibility risk, and test evidence. Update docs with behavior changes and complete the pull-request checklist.
+
+## Releases
+
+Maintainers use semantic versioning with prerelease tags for alpha work. A release must pass CI, build from a clean checkout, match `openmuse.__version__`, include release notes, and be checked on TestPyPI before PyPI.

openmuse_agent-0.3.0a0/GOVERNANCE.md

@@ -0,0 +1,2 @@
+# Governance
+OpenMuse is maintainer-led. Changes to security boundaries, approval semantics, connector scopes, or data retention require an issue, threat-model review, tests, and maintainer approval. Decisions are recorded as ADRs. Releases use semantic versioning.

openmuse_agent-0.3.0a0/LICENSE

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

openmuse_agent-0.3.0a0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: openmuse-agent
+Version: 0.3.0a0
+Summary: A local-first, auditable personal AI agent runtime
+Project-URL: Homepage, https://github.com/tahodev/openmuse
+Project-URL: Issues, https://github.com/tahodev/openmuse/issues
+Author: tahodev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,automation,local-first,personal-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=43
+Requires-Dist: keyring>=25
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenMuse
+
+[![CI](https://github.com/tahodev/openmuse/actions/workflows/ci.yml/badge.svg)](https://github.com/tahodev/openmuse/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tahodev/openmuse?quickstart=1)
+
+A local-first, auditable personal AI agent runtime. OpenMuse separates untrusted planners from typed tools, host-issued approvals, durable tasks, encrypted secrets, and redacted audit history.
+
+## Why OpenMuse is different
+
+The goal is the smallest readable personal-agent runtime whose safety semantics are verified in code and tests:
+
+- **Exact-action approval.** The host signs each approval token against one action's tool and arguments. Tokens expire and can be consumed exactly once. The planner cannot mint approvals, and approving one action never approves a similar-looking one.
+- **Verifiable audit.** Every decision lands in a redacted, hash-chained local log that you can re-verify independently. Change one audited byte and verification fails.
+- **Secrets never reach the model.** Tools receive decrypted secrets through a host callback at execution time. Secret values never appear in planner context, action arguments, tool manifests, or the audit log.
+
+## See the safety boundary in 30 seconds
+
+One simple story: the agent starts a task, pauses before one write, the user approves exactly that action, it runs, and the audit chain proves what happened.
+
+[![Play the real terminal recording](https://asciinema.org/a/MYdPbeccAUeoC8uy.svg)](https://asciinema.org/a/MYdPbeccAUeoC8uy)
+
+This is a real terminal capture. Its raw, replayable cast is also [checked into the repository](docs/assets/openmuse-demo.cast).
+
+## The approval boundary
+
+The planner and everything it reads are untrusted. Only the trusted host can issue an approval, and it issues one for the exact action the user approved:
+
+```mermaid
+flowchart TD
+    U([User])
+    subgraph untrusted["Untrusted"]
+        P["Planner (model)"]
+        X["External content: pages, messages, files"]
+    end
+    subgraph host["Trusted host"]
+        POL["Policy"]
+        AUTH["Approval authority"]
+        VAULT["Secret vault"]
+        EXEC["Tool executor"]
+        AUD["Hash-chained audit log"]
+    end
+    X -.-> P
+    P -->|proposes one typed action| POL
+    POL -->|sensitive action: ask| U
+    U -->|approves this exact action| AUTH
+    AUTH -->|one-time, expiring, action-bound token| EXEC
+    POL -->|allow| EXEC
+    VAULT -->|decrypts via host callback| EXEC
+    EXEC -->|typed result| P
+    POL --> AUD
+    AUTH --> AUD
+    EXEC --> AUD
+```
+
+## Use a real model
+
+`OpenAICompatiblePlanner` supports OpenAI-compatible chat-completions endpoints. Set `OPENAI_API_KEY` and pass the planner to `Agent.run()`. This is an alpha adapter: use a test key and non-sensitive data.
+
+```python
+import os
+from pathlib import Path
+from openmuse.core import Agent
+from openmuse.policy import Policy
+from openmuse.providers import OpenAICompatiblePlanner
+from openmuse.tools import ReadFile
+
+agent = Agent([ReadFile(Path.cwd())], Policy(), Path(".openmuse/audit.jsonl"))
+planner = OpenAICompatiblePlanner(api_key=os.environ["OPENAI_API_KEY"])
+print(agent.run("Read README.md and stop", planner))
+```
+
+The deterministic demo remains the recommended first run because it is free and reproducible.
+
+**Current scope:** an alpha security-primitives runtime and reproducible demo, not a production personal assistant. Unlike [Digger's deployable OpenMuse assistant](https://github.com/diggerhq/openmuse), this project focuses on host-enforced exact-action approval and verifiable local audit trails. The Python distribution is named `openmuse-agent`.
+
+> Independent project. Not affiliated with or endorsed by Meta. No Meta code, branding, or assets are used.
+
+## Run it
+
+The quickest path opens a ready Python environment. In the terminal, run `python examples/e2e_demo.py` so you can inspect and approve the exact write yourself:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tahodev/openmuse?quickstart=1)
+
+Or run locally with Python 3.11+ and Git:
+
+```bash
+git clone https://github.com/tahodev/openmuse.git
+cd openmuse
+python -m venv .venv
+source .venv/bin/activate             # Windows: .venv\Scripts\activate
+pip install -e '.[dev]'
+python examples/e2e_demo.py
+```
+
+The deterministic demo needs no API key. It keeps the existing web-channel and durable-task flow, but makes the one sensitive write and its host-issued approval visible.
+
+## Verify, don't trust
+
+After the demo, independently recompute every audit hash and link:
+
+```bash
+python examples/verify_audit.py
+```
+
+Expected result:
+
+```text
+VERIFIED: 3 records form an intact hash chain
+```
+
+Change any audited byte and verification fails. The verifier is intentionally small: [examples/verify_audit.py](examples/verify_audit.py) calls the public [`verify_chain`](src/openmuse/audit.py) function. The audit contains a blocked attempt, the approved action, and its execution result.
+
+## Status
+
+| Capability | Status |
+|---|---|
+| Typed, budgeted agent loop | Working |
+| Exact-action, expiring, one-time approvals | Working |
+| Workspace file tools + SSRF-resistant public fetch | Working |
+| Redacted hash-chained audit | Working |
+| SQLite task checkpoints/cancel/restart | Working |
+| In-process web channel adapter | Experimental |
+| Envelope-encrypted local secret vault | Experimental |
+| Browser-worker policy envelope | Experimental |
+| Persistent task threads + atomic cron job claims | Working |
+| Credential-free read-only mail/calendar connectors | Working |
+| Production-capable read-only Google Calendar and Gmail connectors | Working |
+| Managed Google OAuth code exchange, refresh, encrypted storage, and OS-keyring master key | Working |
+| [Resource-limited OS process worker](docs/isolated-worker.md) | Working |
+| Kernel/network-isolated browser worker | Not yet |
+| Ephemeral OTP grants + exact-total validation | Working |
+| Searchable, tiered, provenance-verifiable memory + edit/forget | Working |
+
+Do not use OpenMuse with sensitive production accounts yet. “Working” means covered by the current test suite, not externally audited.
+
+## How it works
+
+`Channel -> durable Task -> Planner -> typed Action -> Policy/Approval -> Tool -> typed Result`
+
+The model cannot mint approval tokens. Secret decryption happens through a host callback, not planner context. See [architecture](docs/architecture.md), [threat model](docs/threat-model.md), [product foundation](docs/product-foundation.md), and [roadmap](docs/roadmap.md).
+
+## What OpenMuse is and is not
+
+| In scope today | Not yet |
+|---|---|
+| Typed local tools, bounded loops, exact-action approval, encrypted local vault, durable tasks, audit verification, simulated mail/calendar connectors | Production browser isolation, independently deployed OAuth callback, independent security review, unattended use with sensitive accounts |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [governance](GOVERNANCE.md), and the [code of conduct](CODE_OF_CONDUCT.md). Starter work is tracked with [`good first issue`](https://github.com/tahodev/openmuse/labels/good%20first%20issue) and [`help wanted`](https://github.com/tahodev/openmuse/labels/help%20wanted) labels.
+
+## License
+
+MIT.

openmuse_agent-0.3.0a0/README.md

@@ -0,0 +1,155 @@
+# OpenMuse
+
+[![CI](https://github.com/tahodev/openmuse/actions/workflows/ci.yml/badge.svg)](https://github.com/tahodev/openmuse/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tahodev/openmuse?quickstart=1)
+
+A local-first, auditable personal AI agent runtime. OpenMuse separates untrusted planners from typed tools, host-issued approvals, durable tasks, encrypted secrets, and redacted audit history.
+
+## Why OpenMuse is different
+
+The goal is the smallest readable personal-agent runtime whose safety semantics are verified in code and tests:
+
+- **Exact-action approval.** The host signs each approval token against one action's tool and arguments. Tokens expire and can be consumed exactly once. The planner cannot mint approvals, and approving one action never approves a similar-looking one.
+- **Verifiable audit.** Every decision lands in a redacted, hash-chained local log that you can re-verify independently. Change one audited byte and verification fails.
+- **Secrets never reach the model.** Tools receive decrypted secrets through a host callback at execution time. Secret values never appear in planner context, action arguments, tool manifests, or the audit log.
+
+## See the safety boundary in 30 seconds
+
+One simple story: the agent starts a task, pauses before one write, the user approves exactly that action, it runs, and the audit chain proves what happened.
+
+[![Play the real terminal recording](https://asciinema.org/a/MYdPbeccAUeoC8uy.svg)](https://asciinema.org/a/MYdPbeccAUeoC8uy)
+
+This is a real terminal capture. Its raw, replayable cast is also [checked into the repository](docs/assets/openmuse-demo.cast).
+
+## The approval boundary
+
+The planner and everything it reads are untrusted. Only the trusted host can issue an approval, and it issues one for the exact action the user approved:
+
+```mermaid
+flowchart TD
+    U([User])
+    subgraph untrusted["Untrusted"]
+        P["Planner (model)"]
+        X["External content: pages, messages, files"]
+    end
+    subgraph host["Trusted host"]
+        POL["Policy"]
+        AUTH["Approval authority"]
+        VAULT["Secret vault"]
+        EXEC["Tool executor"]
+        AUD["Hash-chained audit log"]
+    end
+    X -.-> P
+    P -->|proposes one typed action| POL
+    POL -->|sensitive action: ask| U
+    U -->|approves this exact action| AUTH
+    AUTH -->|one-time, expiring, action-bound token| EXEC
+    POL -->|allow| EXEC
+    VAULT -->|decrypts via host callback| EXEC
+    EXEC -->|typed result| P
+    POL --> AUD
+    AUTH --> AUD
+    EXEC --> AUD
+```
+
+## Use a real model
+
+`OpenAICompatiblePlanner` supports OpenAI-compatible chat-completions endpoints. Set `OPENAI_API_KEY` and pass the planner to `Agent.run()`. This is an alpha adapter: use a test key and non-sensitive data.
+
+```python
+import os
+from pathlib import Path
+from openmuse.core import Agent
+from openmuse.policy import Policy
+from openmuse.providers import OpenAICompatiblePlanner
+from openmuse.tools import ReadFile
+
+agent = Agent([ReadFile(Path.cwd())], Policy(), Path(".openmuse/audit.jsonl"))
+planner = OpenAICompatiblePlanner(api_key=os.environ["OPENAI_API_KEY"])
+print(agent.run("Read README.md and stop", planner))
+```
+
+The deterministic demo remains the recommended first run because it is free and reproducible.
+
+**Current scope:** an alpha security-primitives runtime and reproducible demo, not a production personal assistant. Unlike [Digger's deployable OpenMuse assistant](https://github.com/diggerhq/openmuse), this project focuses on host-enforced exact-action approval and verifiable local audit trails. The Python distribution is named `openmuse-agent`.
+
+> Independent project. Not affiliated with or endorsed by Meta. No Meta code, branding, or assets are used.
+
+## Run it
+
+The quickest path opens a ready Python environment. In the terminal, run `python examples/e2e_demo.py` so you can inspect and approve the exact write yourself:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tahodev/openmuse?quickstart=1)
+
+Or run locally with Python 3.11+ and Git:
+
+```bash
+git clone https://github.com/tahodev/openmuse.git
+cd openmuse
+python -m venv .venv
+source .venv/bin/activate             # Windows: .venv\Scripts\activate
+pip install -e '.[dev]'
+python examples/e2e_demo.py
+```
+
+The deterministic demo needs no API key. It keeps the existing web-channel and durable-task flow, but makes the one sensitive write and its host-issued approval visible.
+
+## Verify, don't trust
+
+After the demo, independently recompute every audit hash and link:
+
+```bash
+python examples/verify_audit.py
+```
+
+Expected result:
+
+```text
+VERIFIED: 3 records form an intact hash chain
+```
+
+Change any audited byte and verification fails. The verifier is intentionally small: [examples/verify_audit.py](examples/verify_audit.py) calls the public [`verify_chain`](src/openmuse/audit.py) function. The audit contains a blocked attempt, the approved action, and its execution result.
+
+## Status
+
+| Capability | Status |
+|---|---|
+| Typed, budgeted agent loop | Working |
+| Exact-action, expiring, one-time approvals | Working |
+| Workspace file tools + SSRF-resistant public fetch | Working |
+| Redacted hash-chained audit | Working |
+| SQLite task checkpoints/cancel/restart | Working |
+| In-process web channel adapter | Experimental |
+| Envelope-encrypted local secret vault | Experimental |
+| Browser-worker policy envelope | Experimental |
+| Persistent task threads + atomic cron job claims | Working |
+| Credential-free read-only mail/calendar connectors | Working |
+| Production-capable read-only Google Calendar and Gmail connectors | Working |
+| Managed Google OAuth code exchange, refresh, encrypted storage, and OS-keyring master key | Working |
+| [Resource-limited OS process worker](docs/isolated-worker.md) | Working |
+| Kernel/network-isolated browser worker | Not yet |
+| Ephemeral OTP grants + exact-total validation | Working |
+| Searchable, tiered, provenance-verifiable memory + edit/forget | Working |
+
+Do not use OpenMuse with sensitive production accounts yet. “Working” means covered by the current test suite, not externally audited.
+
+## How it works
+
+`Channel -> durable Task -> Planner -> typed Action -> Policy/Approval -> Tool -> typed Result`
+
+The model cannot mint approval tokens. Secret decryption happens through a host callback, not planner context. See [architecture](docs/architecture.md), [threat model](docs/threat-model.md), [product foundation](docs/product-foundation.md), and [roadmap](docs/roadmap.md).
+
+## What OpenMuse is and is not
+
+| In scope today | Not yet |
+|---|---|
+| Typed local tools, bounded loops, exact-action approval, encrypted local vault, durable tasks, audit verification, simulated mail/calendar connectors | Production browser isolation, independently deployed OAuth callback, independent security review, unattended use with sensitive accounts |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [governance](GOVERNANCE.md), and the [code of conduct](CODE_OF_CONDUCT.md). Starter work is tracked with [`good first issue`](https://github.com/tahodev/openmuse/labels/good%20first%20issue) and [`help wanted`](https://github.com/tahodev/openmuse/labels/help%20wanted) labels.
+
+## License
+
+MIT.

openmuse_agent-0.3.0a0/SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+OpenMuse is alpha software with no production-supported release. Report vulnerabilities using a [private GitHub security advisory](https://github.com/tahodev/openmuse/security/advisories/new), never a public issue.
+
+## Current limits
+
+The local vault encrypts secret values with per-secret AES-256-GCM data keys wrapped by an AES-256-GCM master key. The master key can be stored in the OS keyring through `KeyringMasterKey`, which fails closed when no usable system credential backend exists; hardware-backed storage is not yet integrated, and tools still share the Python process. `FetchURL` resolves a destination once, rejects the entire DNS answer set if any address is non-public, and pins the connection to a validated address while preserving TLS hostname verification; redirects are blocked rather than followed. The hash-chained audit is not externally anchored, and the approval UI is experimental. Use test accounts and non-sensitive data.
+
+See the [threat model](docs/threat-model.md) and [production gate](docs/roadmap.md).

openmuse_agent-0.3.0a0/SUPPORT.md

@@ -0,0 +1,3 @@
+# Support
+
+Use [GitHub issues](https://github.com/tahodev/openmuse/issues) for usage questions and reproducible bug reports. Do not post secrets or vulnerability details publicly. Use a [private GitHub security advisory](https://github.com/tahodev/openmuse/security/advisories/new) for security reports.

openmuse_agent-0.3.0a0/docs/adr/0001-security-first-runtime.md

@@ -0,0 +1,2 @@
+# ADR 0001: Security-first runtime
+Status: accepted. OpenMuse separates untrusted planners from a trusted executor. Tools declare risk and schema; sensitive effects require host-issued approval. This favors inspectability over autonomous breadth.