algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/resources/docs/algo-cli-algorithm-evidence-contract.md

@@ -0,0 +1,60 @@
+---
+title: Algo CLI Algorithm Evidence Contract
+description: Durable distinction between catalog, kernel readiness, runtime use, and measured algorithm effectiveness.
+status: active
+updated: 2026-07-10
+tags: [algo-cli, product-memory, algorithm-evidence, kernel-readiness, effectiveness]
+---
+
+# Algo CLI Algorithm Evidence Contract
+
+Algo CLI records ideas, contracts, runtime capabilities, and empirical evidence
+at different layers. Those layers must not be collapsed into one “active” claim.
+
+## What each layer proves
+
+| Layer | It proves | It does not prove |
+|---|---|---|
+| `ALGO.md` catalog | An algorithm or pattern has a reviewed contract and intended use. | That normal runtime traffic executes it. |
+| Kernel manifest and `/kernel check` | Modules import, slash roots resolve, metadata is valid, and active action declarations have risk contracts. | Workload execution or benefit. |
+| Action registry | A callable/command has coverage, risk, provider, and approval metadata. | Algorithmic correctness or effectiveness. |
+| Tests and runtime evidence | The real boundary behaves as specified for measured inputs and fallbacks. | General benefit beyond the evaluated corpus. |
+
+Use precise states: `planned`, `preview`, `contract-ready`, `observed`,
+`effective`, `limited`, or `regressing`. Contract readiness is valuable, but it
+must never be rendered as empirical effectiveness.
+
+## Evidence rule
+
+An effectiveness claim requires all of the following:
+
+1. The actual production boundary is exercised, not a duplicate test-only
+   implementation.
+2. Deterministic positive, negative, and fallback cases pass.
+3. The result exposes enough provenance or telemetry to explain the decision.
+4. A pinned baseline or parity oracle is used when improvement is claimed.
+5. Missing prerequisites and runtime errors are reported as `unavailable`,
+   `error`, or `fail`; they never become a fabricated pass.
+
+Critical safety bypasses are vetoes. Adding many trivial declarations cannot
+average away one failed required check.
+
+## Bounded live evidence
+
+The local algorithm-effectiveness probe uses the persisted canonical catalog
+embedding as a deterministic query vector and makes no model or network call.
+It exercises the production hybrid retrieval path twice and checks lexical
+provenance and corpus-cache reuse, exact-vector and normalized-matrix reuse,
+fusion mode against embedding coverage, stable top-k parity above its measured
+crossover, bounded TinyLFU reuse, and value-aware embedding-tier arithmetic.
+It also runs the production durable-memory admission path in an isolated
+temporary state and requires one safe write, duplicate/secret rejection, and
+metadata-only persistence. The probe passes only when every required check
+passes.
+
+Do not preserve transient benchmark numbers here. Measurements belong in probe
+output or dated audits; this document preserves the evidence contract.
+
+Authoritative implementation boundaries: `evals/algorithm_effectiveness.py`,
+`kernels/manifest.py`, `action_registry.py`, `perf_telemetry.py`, and
+`docs/ALGO.md`.

algo_cli/resources/docs/algo-cli-execution-verification-contract.md

@@ -0,0 +1,59 @@
+---
+title: Algo CLI Execution and Verification Contract
+description: Durable rules for runtime entrypoints, policy preflight, mutation ownership, evidence, and failure handling.
+status: active
+updated: 2026-07-10
+tags: [algo-cli, product-memory, execution-verification, tool-policy, mutation-owner]
+---
+
+# Algo CLI Execution and Verification Contract
+
+This record describes the runtime invariants that must survive UI, model, and
+pipeline changes. It explains ownership and evidence; procedural tool-selection
+skills may provide narrower how-to guidance.
+
+## Execution surfaces
+
+- Normal model-callable tools perform work and return structured results.
+- `session_slash` owns deterministic working-directory navigation commands.
+- `session_command` owns non-file session controls and registered slash routes.
+
+Every model-invoked tool path must pass through the shared runtime preflight
+before execution. The preflight resolves runtime arguments, capability tier,
+policy-chain verdict, QoS metadata, and approval requirements. Unknown or
+disallowed actions fail closed; a parallel path may not bypass the same gate
+used by a serial path.
+
+## Mutation ownership
+
+A multi-agent team has one write owner. Specialists receive bounded read-only
+contexts and return evidence; the integration pipeline alone may edit the
+workspace. Child work does not recursively delegate or create competing
+writers. The integration owner remains subject to the same policy, approval,
+required-change, and verification rules as an ordinary run.
+
+## Evidence for completed work
+
+- Use file mutation tools for edits; use shell execution for tests, lint,
+  type-checking, builds, status, and diff evidence.
+- A mutation is not complete merely because a tool returned text that sounds
+  successful. Verify the changed artifact and the smallest relevant behavior.
+- Record Git status/diff evidence when a repository is available. If it is not,
+  preserve an explicit manual-verification warning instead of inventing proof.
+- Keep `worked`, `failed`, `skipped`, and `denied` outcomes distinct in the
+  attempt ledger and telemetry.
+- Do not cosmetically retry a recent identical failed signature; change the
+  hypothesis, input, or tool, or report the blocker.
+
+## Failure and fallback
+
+Approval denial, unsafe input, unknown action, missing verification evidence,
+and incompatible runtime state are explicit outcomes. Fallbacks must remain
+bounded and observable; swallowed exceptions and silent policy downgrades are
+not valid recovery.
+
+Authoritative implementation boundaries: `tool_runtime.py`, `tool_policy.py`,
+`agent_pipeline.py`, `agent_threads.py`, `runtime_services.py`, and
+`session_commands.py`. Focused tests prove behavior; registry declarations only
+describe the available contract.
+

algo_cli/resources/docs/algo-cli-memory-lifecycle-contract.md

@@ -0,0 +1,72 @@
+---
+title: Algo CLI Memory Lifecycle Contract
+description: Durable placement, authority, capture, deduplication, retention, and readiness rules across Algo CLI memory systems.
+status: active
+updated: 2026-07-10
+tags: [algo-cli, product-memory, memory-lifecycle, retrieval-authority, retention]
+---
+
+# Algo CLI Memory Lifecycle Contract
+
+This record defines where durable context belongs and how each memory layer is
+allowed to influence work. It is a placement and lifecycle contract, not a
+product-identity page or a current-state dashboard.
+
+## Placement matrix
+
+| Information | Durable home | Rule |
+|---|---|---|
+| One stable fact or standing preference needed on most turns | `memory.json` through explicit `remember` or bounded completion capture | Keep it atomic and concise because it is always-on context. |
+| A behavioral lesson the user explicitly asks to retain | `lessons-learned.md` through `append_lesson` | Capture the lesson, not a transcript. |
+| A multi-paragraph product decision or invariant | Curated harness memory | State the contract, rationale, failure behavior, and authoritative modules. |
+| A procedure, runbook, dated audit, or current snapshot | Curated wiki | Make its date and status explicit; archive it when superseded. |
+| Entity relationships and ranked associations | index-compute-lab | Use for navigation and discovery, not as proof of a live fact. |
+| Optional associative/session recall | Intuition or Echo Veil | Treat as a hint layer; it is never canonical by itself. |
+
+Do not copy the same prose across tiers. Promote a small atomic fact to
+always-on memory only when its value justifies prompt cost; keep supporting
+detail in one RAG document.
+
+## Authority and retrieval
+
+User instructions and verified live files, endpoints, and tool results outrank
+all persisted memory. Lessons, harness records, graph results, and optional
+recall blocks are navigation evidence. Consequential claims must be checked at
+the live source before action.
+
+Retrieval must retain source identity and rank provenance. Incomplete vector
+coverage is an availability condition, not a relevance signal: newly added
+records must remain discoverable through lexical evidence while embeddings
+catch up.
+
+## Capture, cleanup, and retention
+
+- Automatic capture runs only after a normally completed chat or runtime-agent
+  turn and examines only the original user text. It requires an explicit durable
+  marker, rejects quoted/code/transient/task/secret/PII input, normalizes before
+  exact/Jaccard deduplication, and writes at most one entry per turn.
+- Daily writes, fingerprint metadata, and total memory characters are capped.
+  Rejected text is never persisted; the sidecar contains timestamps and hashes,
+  not memory bodies. `/memory-auto status|on|off` exposes the persisted opt-out.
+- Explicit `remember` and `append_lesson` requests suppress automatic capture in
+  that turn so the same statement is not written twice.
+- Batch reconciliation must hold the memory lock, write atomically, and retain a
+  pre-change backup.
+- Prefer consolidation and explicit historical status over silent deletion.
+- Do not enable destructive time-based decay until records carry trustworthy
+  timestamps and use/access evidence.
+- A dated implementation observation belongs in a wiki or audit, not in this
+  durable contract.
+
+## Readiness vocabulary
+
+Memory readiness is multi-dimensional. `installed`, `enabled`, `write_wired`,
+`retrieval_wired`, and `persistence_wired` are separate claims. A package or
+feature flag alone must never be presented as a functioning write/recall path.
+The score accepts disabled Echo Veil; if enabled, installation and all three
+wiring stages must be proven or the critical memory gate fails.
+
+Authoritative implementation boundaries: `config.py`, `memory_candidates.py`,
+`memory_runtime.py`, `context_budget.py`, `harness.py`, and
+`memory_echo_veil.py`. When this document and live behavior disagree, verify
+the code and update this contract.

algo_cli/resources/docs/harness-extension-cleanup-recommendation.md

@@ -0,0 +1,41 @@
+# Structured Codex plugin metadata indexing
+
+**Status:** Completed and verified.
+
+## Current State
+
+When the user explicitly enables external harness sources, Algo CLI indexes Codex plugin metadata without treating it as undifferentiated extension noise:
+
+- `codex:extension` for `SKILL.md` files
+- `codex:plugin` for `.codex-plugin/plugin.json` manifests
+- `codex:install` for `.codex-remote-plugin-install.json` install receipts
+- `codex:connector` for `.app.json` connector metadata
+- `codex:mcp` for `.mcp.json` server declarations
+- `codex:command` for plugin command markdown
+- `codex:agent` for plugin agent profiles
+
+JSON metadata is normalized into useful titles, descriptions, and tags. For example, Google Drive connector records surface as `Codex app connectors: google-drive` instead of raw `.app` filenames, and remote install receipts surface as `Codex plugin install: google-drive`.
+
+## Why This Matters
+
+The original audit found that extension records could dominate the harness index and dilute semantic retrieval. The current implementation keeps the useful plugin capability information while avoiding raw, low-context metadata records.
+
+The live harness quality report distinguishes generic extension records from structured plugin metadata, so a larger Codex plugin cache no longer makes the harness look unhealthy by itself.
+
+## Verification
+
+Relevant tests:
+
+- `tests/test_harness.py::test_iter_files_supports_nested_plugin_cache_globs`
+- `tests/test_harness.py::test_codex_plugin_metadata_sources_are_builtin_harness_sources`
+- `tests/test_harness.py::test_codex_plugin_manifest_record_uses_json_metadata`
+- `tests/test_harness.py::test_codex_remote_plugin_install_record_uses_json_metadata`
+- `tests/test_harness.py::test_codex_connector_and_mcp_records_use_json_metadata`
+- `tests/test_harness.py::test_quality_allows_low_project_share_when_structured_plugin_metadata_is_indexed`
+
+Operational checks:
+
+- Run `/harness status` to inspect counts and quality.
+- Run `/harness score` to grade readiness against the current Algo CLI review gates.
+- Run `/harness refresh` after plugin/source changes.
+- Run `/harness embed` if pending embeddings appear.

algo_cli/resources/docs/index-compute-lab-integration.md

@@ -0,0 +1,32 @@
+# index-compute-lab ↔ Algo CLI integration
+
+**Lab path (default):** `~/index-compute-lab`; override it with `ALGO_CLI_INDEX_COMPUTE_LAB_ROOT`.
+
+## Seamless context (every model / provider)
+
+1. **Auto-inject (opt-in, default OFF)** — After `/icl on`, Algo CLI runs `query.py ask` and prepends a `## Knowledge Graph (index-compute-lab)` block to the turn. This content becomes part of the provider request, including when a cloud model is selected.
+
+2. **Harness index** — `atoms/*.md` reports and notes are indexed dynamically under harness `index-compute-lab` (via `atoms_dir()` in `all_source_roots()`) and participate in vector RAG (`/harness refresh`). Do **not** also list the lab in `~/.algo_cli/harness_roots.json`; that path is for user extras only and previously double-indexed agent notes.
+
+3. **Tool** — `query_knowledge_graph` for explicit follow-up questions.
+
+## Configuration
+
+| Setting | Default |
+|---------|---------|
+| `Config.index_compute_lab_auto_inject` | `false` |
+| `ALGO_CLI_INDEX_COMPUTE_LAB_ROOT` | overrides path |
+| `INDEX_COMPUTE_LAB_ROOT` | legacy env alias |
+
+## Commands
+
+- `/icl` — status (root, assets ready, auto-inject on/off)
+- `/icl on` / `/icl off` — toggle auto-inject
+- `/icl ask <question>` — one-off graph query
+- `/icl path` — show resolved root
+
+## First run
+
+If a legacy `index-compute-lab` entry is present in `~/.algo_cli/harness_roots.json`, startup removes it (lab indexing is dynamic). Run `/harness refresh` once to drop any duplicate atom records, then `/harness embed` for vectors.
+
+**Last updated:** 2026-07

algo_cli/resources/docs/inference-harness-loop-blueprint-2026-06.md

@@ -0,0 +1,55 @@
+# Inference Harness Loop Blueprint
+
+Date: 2026-06-12
+
+This note captures how EOSD, ALK-delta, AVEE, and CPDI should be wired into the Algo CLI agent loop.
+
+## Architecture
+
+These algorithms live below the normal hosted-API harness line.
+
+- Algo CLI agent loop: orchestration, Agent Blocks, policy, routing metadata, telemetry display, and fallback decisions.
+- Inference gateway: one OpenAI/Anthropic-compatible facade that accepts agent requests, chooses hosted or local routes, and returns normalized provenance.
+- Local inference engine: vLLM/SGLang fork or adapter where decode, KV, forward-pass, and scheduler changes are implemented.
+
+The agent loop should not pretend it can implement EOSD, ALK-delta, AVEE, or CPDI through an ordinary hosted model call. It should guide implementation plans toward the local engine and expose only stable policy knobs upward.
+
+## Algorithm Placement
+
+EOSD belongs in the speculative decoding loop. Before each draft round, compute prefix-visible draft entropy, map it through a calibrated `beta_hat = g(H)`, choose the speculative depth `k`, and record realized `k`, acceptance rate, and tokens/sec. EOSD remains lossless when `k` is chosen before drafting from prefix information.
+
+ALK-delta belongs in the KV cache manager or PagedAttention layer. The engine stores anchors, low-rank factors, and sparse residuals, then exposes a per-request certified attention-output perturbation bound. The harness consumes that scalar for policy and fallback.
+
+AVEE belongs in the model forward pass. It requires calibrated auxiliary exit heads and an e-process accumulator. The harness supplies `risk_delta`, while the engine returns exit-layer telemetry and measured agreement.
+
+CPDI belongs in the serving scheduler. The harness supplies `priority_weight`; the scheduler allocates prefill/decode work using normalized remaining work and returns queue and latency telemetry.
+
+## Gateway Contract
+
+Request metadata should stay small:
+
+- `model`
+- `messages`
+- `risk_delta`
+- `priority_weight`
+- `lossless_required`
+
+Response provenance should include:
+
+- engine route and fallback reason
+- realized speedup
+- EOSD acceptance stats
+- ALK-delta KV certificate
+- AVEE exit histogram
+- CPDI queue and latency metrics
+
+## Build Order
+
+1. Stand up a vanilla local-engine route behind the gateway and verify routing, telemetry, and hosted fallback.
+2. Add EOSD first because deterministic exact-output regression tests can check the losslessness contract.
+3. Add CPDI scheduler experiments next because they are mostly scheduler logic.
+4. Add ALK-delta and AVEE last because they require cache/kernel work, calibration, and stricter quality validation.
+
+## Agent Loop Integration
+
+`algo_cli.inference_harness` detects inference-engine tasks and injects this contract into each Agent Block system prompt. Normal agent tasks are unaffected.

algo_cli/resources/docs/main-split-map.md

@@ -0,0 +1,35 @@
+# main.py decomposition map
+
+`algo_cli/main.py` is the CLI orchestrator. Split it incrementally; keep `from algo_cli import main` working for tests and scripts.
+
+## Done
+
+| Module | Responsibility |
+|--------|----------------|
+| `chat_protocol.py` | `get_attr`, `normalize_tool_call`, `serialize_tool_call`, `collapse_tool_history_for_gemini`, `normalize_message` |
+| `model_routing.py` | Cloud/local/xAI host routing and model name classifiers |
+| `runtime_services.py` | `create_client`, `client_for_model`, Ollama serve, harness-gateway lifecycle, `apply_tool_runtime_env`, readiness caches |
+| `context_budget.py` | Token estimates, `build_system_prompt`, pruning, compaction, `context_status`, `unpack_embed` cache keys, `estimate_usage_with_system_prompt` |
+| `perf_telemetry.py` | Perf JSONL buffer, chat/tool/compaction metrics, embed perf log, `/perf` summary |
+| `tool_runtime.py` | `run_tool`, approval, attempt ledger, reflex augmentation, reflection checkpoint, pipeline tool execution |
+| `agent_pipeline.py` | `run_agent_block`, `run_agent_pipeline`, required-change contract, recovery/replan, session pipeline buffer |
+| `slash_dispatch.py` | `SLASH_COMMANDS`, `SlashCommandCompleter`, `handle_command` (delegates to `main` for handlers) |
+| `session_commands.py` | Model-invokable `/read`, `/ls`, `/cd`, `/cwd` |
+| `oneshot.py` | `--oneshot --json` NDJSON mode |
+| `agent_blocks.py` | Pipeline definitions and TOML loading |
+
+`main.py` re-exports moved symbols so `tests/test_main_helpers.py` and `test_verify.py` need no churn.
+
+## Next slices (recommended order)
+
+1. **Handler extraction** — move `handle_*_command` and auth helpers out of `main.py` so `slash_dispatch` does not lazy-import `main` (optional cleanup).
+
+## Keep in `main.py`
+
+- `main()` REPL loop, `parse_args`, migration/onboarding hooks
+- `agent_loop` until `tool_runtime` exists (then thin wrapper only)
+
+## Tests
+
+- Prefer unit tests on new modules (`test_chat_protocol.py`, `test_model_routing.py`) over growing `test_main_helpers.py`.
+- After each slice: `ruff check algo_cli tests` and `pytest -q`.

algo_cli/resources/docs/privacy-and-context.md

@@ -0,0 +1,48 @@
+---
+title: Privacy and local context
+description: How Algo CLI discovers, stores, and sends local context.
+status: active
+tags: [privacy, harness, cloud, context, consent]
+---
+
+# Privacy and local context
+
+Algo CLI starts with repository-provided documentation, skills, and files that the user creates under `~/.algo_cli`. It does not index other agent stores by default.
+
+## Always-sent model context
+
+Every normal chat request sends the active conversation and the assembled Algo CLI system context to the selected inference provider. The assembled context includes `SOUL.md`, `IDENTITY.md`, `USER.md`, saved memories, and relevant retrieved lessons when available. If the active model uses a cloud provider, this content may leave the machine.
+
+Automatic memory capture is enabled by default. Its bounded completion gate may save an explicit, high-confidence durable statement after a successful turn. `/memory-auto off` stops future automatic captures; it does not remove existing entries. Inspect existing entries with `/memories` and remove one with `/forget ID`.
+
+## Optional sources
+
+- `/harness external on` enables discovery of supported local agent stores such as Codex, Claude, OpenClaw, Mercury, and shared agent skills.
+- `/icl on` enables index-compute-lab retrieval and automatic graph context.
+- `/code-rag on` enables working-directory source indexing and relevant-snippet retrieval.
+- `/skills on` enables bounded run-summary capture and automatic local skill-candidate crystallization.
+- Entries in `~/.algo_cli/harness_roots.json` are treated as explicit user-provided roots.
+
+Disable an optional source with `/harness external off`, `/icl off`, or `/code-rag off`. Changing either harness setting rebuilds the generated harness index so disabled records are removed. `/code-rag off` also purges every persisted code-index file.
+
+## Working-directory code retrieval boundary
+
+- **Command boundary:** `/code-rag status` is read-only. `/code-rag on` records the current explicit consent version; a legacy saved `code_rag_enabled: true` value does not count as consent. Model-invoked `on` and `off` commands require approval.
+- **Index boundary:** when enabled, Algo CLI scans supported source files beneath the active cwd, skips hidden/build/vendor directories and secret-like filenames, rejects symlinks that escape the cwd, and stores chunks plus local embeddings in `~/.algo_cli/code_index/`. `/code-rag off` deletes those generated index files, not the source files.
+- **Provider boundary:** embeddings are generated through local Ollama. Retrieved source snippets are then added to the active chat request, so they may leave the machine when the selected inference provider is remote.
+
+## Skill run history
+
+Skill run-history capture and automatic crystallization are off by default. `/skills on` opts in to bounded completed-run summaries at `~/.algo_cli/private/run_history.jsonl`. After the configured interval, a genuinely local, non-embedding Ollama model may turn qualifying patterns into quarantined skill candidates for explicit review. Crystallization skips when no such local model is available and never falls back to a cloud provider. `/skills off` stops future capture and automatic crystallization but does not delete prior history. Older installs may also have a legacy read-only input at `~/.algo_cli/run_history.jsonl`.
+
+## Provider boundary
+
+Retrieved context becomes part of the model request. If the selected model uses a cloud provider, enabled local context may leave the machine. Enable external sources only when their content is appropriate for the selected provider.
+
+Algo CLI removes common credential forms and indexes connector/MCP JSON as metadata only. Redaction is a defense-in-depth measure, not a guarantee that arbitrary sensitive prose will be detected.
+
+## Local state
+
+Runtime configuration, generated indexes, memories, identity files, and credentials live under `~/.algo_cli` unless `ALGO_CLI_CONFIG_DIR` overrides the location. These files are not part of the source distribution. Keep the directory private and exclude it from repositories and backups that are shared publicly.
+
+Automatic memory capture is bounded and privacy-gated. Inspect or disable it with `/memory-auto status` and `/memory-auto off`.