Publish portable Agent Gearbox core

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install .
+      - run: gearbox --help
+      - run: tools/verify

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.coverage
+.pytest_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+evidence/local/

ARCHITECTURE.md

@@ -0,0 +1,63 @@
+# Architecture
+
+```text
+primary developer
+       |
+       v
+request + content-addressed authority
+       |
+       v
+admission and gear selection
+       |
+       +----------------------+
+       |                      |
+       v                      v
+exact deterministic argv   bounded helper transport
+                              |
+                     staged allowlisted context
+       |                      |
+       +----------+-----------+
+                  v
+            raw private evidence
+                  |
+       external Context Firewall adapter
+                  |
+                  v
+compact result + value receipt + operator indicator
+                  |
+                  v
+primary developer retains completion ownership
+```
+
+## Internal modules
+
+The reference core currently keeps its small executable surface in
+`src/opsle_gearbox/core.py`:
+
+- authority and policy validation;
+- request and budget admission;
+- safe source selection and staging;
+- deterministic executor;
+- injected helper transport boundary;
+- output-contract and staged-change validation;
+- compact result and Visible Value receipt generation.
+
+`src/opsle_gearbox/cli.py` provides the deterministic command-line interface.
+
+## External dependencies
+
+- **Context Firewall**: deterministic adapters for command/helper raw evidence.
+- **Decision Evidence Protocol**: independent receipt/result conformance.
+- **Agent Trajectory Profiler**: observational execution telemetry.
+- **Routing Policy**: chooses a model/provider profile after cognitive
+  admission; the core policy currently binds an already selected profile.
+- **Execution Authorization / Resource Claims**: stronger external authority
+  where a deployment requires capabilities, leases, or fencing.
+- **Ephemeral Workers / Verifiable Handoff**: optional isolation and durable
+  artifact transfer.
+
+## Explicit exclusions
+
+The repository owns no objective graph, durable scheduler, queue, wakeup,
+discovery, recovery ladder, global pause, persistent hierarchy, provider pool,
+or product completion state.

BENCHMARK.md

@@ -0,0 +1,19 @@
+# Benchmark plan
+
+No benchmark-ready claim is made.
+
+Future controlled evaluation should freeze:
+
+- content-addressed task identities and source context;
+- deterministic-eligible and bounded-cognitive task strata;
+- direct-primary and admitted-Gearbox arms;
+- exact model/provider/effort identities where cognition is used;
+- an independent correctness and completion oracle;
+- raw evidence and compact result identities;
+- primary-model turns, provider-recorded tokens, provider sessions, elapsed
+  transport wait, escalations, retries, and operator intervention;
+- randomized or blinded allocation appropriate to the task set.
+
+Correctness and authority violations gate every efficiency result. Ordinary
+provider-free runs and value receipts remain observational. Byte measurements
+must not be converted into token, cost, latency, or causal savings claims.

LIMITATIONS.md

@@ -0,0 +1,21 @@
+# Known limitations
+
+- No production cognitive/provider transport is bundled or accepted.
+- Helper isolation is an injected-transport responsibility and is not proven by
+  the core interface.
+- Context Firewall reduction is not bundled; the compact result intentionally
+  exposes only terminal facts, hashes, counts, and artifact locators.
+- Symbol selection supports Python only.
+- The reference JSON-schema validator implements a documented subset, not full
+  JSON Schema.
+- Deterministic commands are exact policy entries rather than a portable command
+  catalog or semantic tool registry.
+- Raw byte ceilings are evaluated after deterministic subprocess completion;
+  an authorized command can temporarily produce more bytes than its ceiling.
+- Run idempotence is filesystem-local and does not provide distributed locking.
+- The prototype does not apply staged helper writes to the source repository.
+- No controlled benchmark establishes correctness preservation, intelligence
+  savings, context savings, latency reduction, monetary value, or avoided
+  provider sessions.
+- A provider-session count of zero is direct telemetry only, not a counterfactual
+  savings claim.

NOTICE

@@ -0,0 +1,7 @@
+Agent Gearbox
+Copyright (C) 2026 Taslos
+
+This work includes code adapted from the AGPL-3.0-licensed Taslos Tasks
+implementation at commit 7734caf208366a0515cf4d78efc17a86363f2238.
+
+Public extraction and canonical boundary documentation are maintained by Opsle.

PROVENANCE.md

@@ -0,0 +1,31 @@
+# Provenance
+
+The public reference core was extracted on 2026-08-29 from the private active
+Taslos Tasks repository at commit
+`7734caf208366a0515cf4d78efc17a86363f2238`.
+
+The predecessor Gearbox entered that repository in commit
+`80f0830e26b938f6abe8fc688b9b1f49283ef34f` under `ops/gearbox/`. The reusable
+algorithms adapted here include:
+
+- strict request/key validation;
+- exact repository identity and normalized path checks;
+- content-addressed file, line, symbol, and new-file selections;
+- safe file reads and source-drift checks;
+- deterministic Python symbol range resolution;
+- private raw artifacts and compact result accounting;
+- provider-session, command, context, output, timeout, and cleanup bounds;
+- one blocking delivery with no retry or fallback.
+
+The public implementation was rewritten around the canonical primary-developer
+Gearbox boundary established by `opsle/research` PR #7. It does not copy or
+publish Taslos Tasks product code, databases, credentials, production state,
+acceptance transcripts, private evidence, systemd units, installed Codex schema
+paths, app-server configuration, or Durable Supervisor machinery.
+
+The predecessor source is AGPL-3.0. This derived repository therefore preserves
+AGPL-3.0-only licensing and records the original copyright in `NOTICE`.
+
+Git history remains attributable through the exact source and introduction
+commits above. Future extraction should cite both this public revision and the
+private source revision when authorized to do so.

README.md

@@ -0,0 +1,122 @@
+# Agent Gearbox
+
+> Stop using intelligence for work that does not require intelligence.
+
+Agent Gearbox lets a powerful primary developer delegate routine operations and
+bounded work to deterministic software or less expensive models, then receive
+only the compact result needed to continue.
+
+This repository contains the public provider-free reference core. It is a
+`PROTOTYPED` mechanism, not evidence of comparative benefit or production
+readiness.
+
+## What exists
+
+- exact, content-addressed authority policies;
+- deterministic-versus-helper gear admission;
+- exact model, effort, provider-session, command, context, raw-output, return,
+  and timeout budgets;
+- deterministic commands admitted by exact argv rather than shell text;
+- content-addressed `file`, `lines`, `symbols`, and `new` context selections;
+- private staged workspaces that never write into the source repository;
+- one injected helper transport, one attempt, no retry or fallback;
+- raw artifact hashes and locators outside the compact result;
+- one compact result on stdout and a named operator indicator on stderr;
+- an `opsle.value-receipt.v1` sidecar with bounded observational claims.
+
+The bundled CLI executes deterministic gears only. Cognitive execution requires
+a separately supplied `HelperTransport` integration. The core rejects a helper
+request when no transport is present; it never silently falls back.
+
+## What does not exist
+
+Gearbox is not a durable supervisor, queue, scheduler, discovery engine,
+retry/recovery controller, persistent agent hierarchy, exact-session resume
+mechanism, general autonomous-task platform, or provider router.
+
+Context Firewall is an external integration. Gearbox decides where bounded work
+executes; Context Firewall decides what decision-relevant evidence returns. The
+reference core returns hashes, terminal facts, artifact locators, and escalation
+state without embedding raw process output.
+
+## Request shape
+
+```json
+{
+  "schema": "opsle.gearbox.request.v1",
+  "task": {
+    "argv": ["git", "status", "--short", "--branch"]
+  },
+  "task_type": "git",
+  "requested_gear": "git-status",
+  "allowed_context": {
+    "repository": "/absolute/git/root",
+    "selections": [],
+    "writable_paths": []
+  },
+  "output_contract": {
+    "schema": {
+      "type": "object",
+      "properties": {},
+      "required": []
+    }
+  },
+  "authority": {
+    "policy_path": "/absolute/reviewed-policy.json",
+    "policy_sha256": "lowercase-sha256"
+  },
+  "budget": {
+    "timeout_seconds": 30,
+    "max_raw_bytes": 1048576,
+    "max_return_bytes": 8192,
+    "max_context_bytes": 0,
+    "max_commands": 1,
+    "max_provider_sessions": 0
+  }
+}
+```
+
+Policies bind a gear name to one kind, authorized task types, and either an
+exact deterministic argv plus executable path/hash or a helper
+transport/model/effort/session profile. The request binds the policy by SHA-256.
+
+## CLI
+
+After reviewing and hashing a policy and request:
+
+```text
+PYTHONPATH=src python3 -m opsle_gearbox.cli \
+  --request /private/request.json \
+  --state /private/gearbox-state \
+  --receipt /private/value-receipt.json
+```
+
+Canonical result JSON is written to stdout. The concise `[Gearbox] ...`
+indicator is written to stderr. Raw stdout/stderr and helper evidence stay under
+the mode-0700 state root.
+
+## Verification
+
+```text
+tools/verify
+```
+
+The suite is provider-free and covers deterministic execution, idempotence,
+authority drift, exact command admission, context hashing and selection,
+symlink/sensitive-path rejection, helper transport absence, model/effort,
+command and context budgets, staged-only writes, termination, compact result,
+Visible Value receipt, and stdout/stderr separation.
+
+## Documents
+
+- [THEORY.md](THEORY.md) — falsifiable problem and mechanism.
+- [SPEC.md](SPEC.md) — normative request, execution, and result contract.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — component and dependency boundaries.
+- [SECURITY.md](SECURITY.md) — trust assumptions and fail-closed behavior.
+- [LIMITATIONS.md](LIMITATIONS.md) — current evidence ceiling.
+- [PROVENANCE.md](PROVENANCE.md) — source extraction and licensing record.
+- [BENCHMARK.md](BENCHMARK.md) — future controlled evidence plan.
+
+## License
+
+AGPL-3.0-only. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

SECURITY.md

@@ -0,0 +1,43 @@
+# Security boundary
+
+## Trusted inputs
+
+- the primary developer or reviewed caller;
+- the exact authority-policy bytes bound by SHA-256;
+- the local operating system and Python runtime;
+- the injected helper transport and any isolation it claims to enforce.
+
+## Untrusted inputs
+
+- task requests before admission;
+- source repositories and selected files;
+- deterministic command output;
+- helper stdout, stderr, mutations, and final result;
+- stale, malformed, partial, or over-budget evidence.
+
+## Enforced by this core
+
+- strict request and policy fields;
+- exact deterministic argv;
+- no shell interpolation;
+- one attempt and no fallback;
+- exact repository identity;
+- normalized, non-sensitive, non-symlink content paths;
+- source hashes and revalidation;
+- helper context and write allowlists;
+- model, effort, command, provider-session, output, and cleanup checks;
+- raw evidence retained outside the compact return;
+- terminal escalation on drift or uncertainty.
+
+## Not enforced by this core
+
+The `HelperTransport` boundary cannot itself prove filesystem, network,
+credential, subprocess, provider, or model isolation. A production transport
+MUST enforce those controls and SHOULD emit independently verifiable receipts.
+No production helper transport is bundled in version 0.1.0.
+
+Deterministic policy authors are responsible for choosing commands that are safe
+for the declared task. Exact admission prevents request expansion; it does not
+make an unsafe authorized command safe.
+
+Report vulnerabilities privately through GitHub's security advisory interface.