chaseos-core 0.1.0

ChaseOS Core is an MIT-licensed, local-first framework for building governed hybrid-intelligence operating systems. It gives fork owners a safe scaffold for memory, projects, source intake, runtime boundaries, approval-gated automation, agent coordination, and evidence-first writeback across humans, deterministic software, ML, and generative agents.

Core is the public framework layer. Your private identity, projects, logs, credentials, provider state, and live runtime memory belong in a separate private ChaseOS instance.

Why ChaseOS Core

Most agent frameworks optimize for capability. Core optimizes for authority — what an automated system is allowed to do, who is accountable for it, and what evidence exists afterward. That shows up as three concrete defaults:

• Fail-closed, not fail-open. Adapters without a bound backend deny rather than proceed. Provider connections start read_only; writes and external egress are approval-gated.
• Modality before provider. The Autonomous Operator Runtime decides whether a step belongs to a human, deterministic code, an ML model, or a generative agent before it picks a runtime — and can derive the approval plan without executing anything.
• Truth is promoted, not written. Captures land in quarantine; canonical knowledge is reached through an explicit review gate, not direct agent writeback.

If you're evaluating the design, start with docs/ARCHITECTURE.md.

Documentation

What Works Today

AOR and Approval Preflight

The Autonomous Operator Runtime is not agent-only orchestration. Its expanded contract selects the appropriate modality for each material step before runtime/provider selection:

• human for accountability, ambiguity, liability, and protected decisions;
• rules/code for exact, stable, security-sensitive, or authority-bearing operations;
• ML/statistics for versioned prediction over structured historical data;
• generative AI for bounded interpretation, synthesis, language, and flexible planning.

The first Core foothold is a fail-closed, read-only Decision Modality Router:

chaseos decision-route inspect docs/runtime/Decision-Contract.example.json --json

It validates the route and produces an approval plan naming the accountable human, exact decision scope, reasons, required evidence, and block-on-timeout/denial behavior. It does not execute the route. See 06_AGENTS/Autonomous-Operator-Runtime.md and docs/governance/Approval-Center.md.

Scaffold / Experimental Surfaces

These surfaces are present as Core-safe scaffolds or bounded footholds. Treat them as building blocks, not fully enabled production integrations:

• provider manifests for Discord, Telegram, Slack, WhatsApp Business Cloud, WhatsApp personal lab, iMessage Mac, GitHub, and local files;
• Studio product-surface contracts and launch references for apps built above Core;
• adapter manifests and runtime profile examples for external agent runtimes;
• acquisition/source-pack, graph, memory, subagent, OSRIL, operator-surface, and AOR modules;
• optional browser and voice extras declared in pyproject.toml.

What This Repository Contains

• Framework documentation for the ChaseOS control plane.
• Templates for notes, projects, logs, runtime profiles, approvals, and audits.
• Governance patterns for approval-gated writes and evidence-first promotion.
• Adapter standards for external runtimes and model/tool surfaces.
• Example folders that can be copied into a private deployment.
• The lean MIT Core CLI entrypoint: chaseos = runtime.cli.core_main:main.
• Local-first runtime modules for capture, schedules, connections, commerce scaffolding, AOR, Gate interfaces, graph/memory inspection, and bounded operator surfaces.
• Studio product-surface contracts for the application layer built above Core.

What This Repository Intentionally Does Not Contain

• Personal notes or private project state.
• Live runtime logs, approval queues, agent-bus state, or private schedules.
• Credential values, API keys, tokens, private keys, or provider secrets.
• Provider-specific deployment state or authenticated account bindings.
• Machine-local paths or operator-specific usernames.
• Proprietary/private Studio builds or packaged installers.
• Public write authority to canonical knowledge without review/promotion.

Intended Use

Use Core as a starter kit and reference model. Private deployments should keep local content, runtime state, and operator records outside the public Core tree.

A healthy fork should:

1. keep chaseos-core as framework/source;
2. create a separate private ChaseOS instance for personal or business operations;
3. copy templates and examples into that private instance only when needed;
4. store credentials in ignored local stores or external secret managers;
5. run read-only/dry-run checks before enabling write, connector, browser, or publication actions;
6. promote durable truth through an explicit review gate instead of direct agent writeback.

ChaseOS Studio should be treated as an application layer over these Core contracts. Ship public contracts and reviewed source-safe docs in the repo; distribute packaged installers such as .exe files through release channels rather than normal source commits.

Use Core in your own project

You do not have to fork Core to use its governance primitives. Install it as a dependency and import what you need — the modality router, the Gate port, and manifest loading all work as plain library calls with no vault directory:

pip install chaseos-core

from runtime.gate_interface import check_runtime_operation, register_gate

# With no provider registered, Core denies by default — it never silently permits.
allowed, reason = check_runtime_operation("vault.write")
assert allowed is False

class MyPolicy:
    def check_runtime_operation(self, operation, **kwargs):
        return operation.endswith(".read"), f"policy decision for {operation}"
    # ... plus the remaining GateProvider methods

register_gate(MyPolicy())

Runnable scripts for the three main entry points are in examples/, and examples/README.md documents which parts of Core need a vault root and which do not.

Quickstart

See docs/getting-started/Quickstart.md for the fork-first setup path.

Minimal validation commands:

python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e .
chaseos version
chaseos doctor --vault-root . --json
chaseos connections providers --json

Run a repo-safe secret audit before publishing a fork:

python - <<'PY'
from runtime.repo_secret_audit import audit_repo_secrets, format_repo_secret_audit
print(format_repo_secret_audit(audit_repo_secrets('.')))
PY

Contributing

Contributions are welcome. See CONTRIBUTING.md for dev setup, scope rules (what belongs in Core versus a private instance), and PR expectations. This project follows the Contributor Covenant.

Security issues should not be filed as public issues — see SECURITY.md.

License

ChaseOS Core is released under the MIT License. See LICENSE.md. Third-party dependency notices are recorded in THIRD_PARTY_NOTICES.md.