minima-cli 0.12.4__tar.gz → 0.13.1__tar.gz

{minima_cli-0.12.4 → minima_cli-0.13.1}/.env.example

@@ -35,8 +35,9 @@ MINIMA_RECALL_RANK_BY=balanced
 MINIMA_RECALL_MAX_AGE_DAYS=0
 # Mubit search budget tier: low | mid | high.
 MINIMA_RECALL_BUDGET=mid
-# Log per-evidence score breakdowns (diagnostic; keep off in prod).
-MINIMA_RECALL_EXPLAIN=false
+# Fraction of recalls (0..1) that request + log Mubit's per-evidence fusion-score
+# breakdown (`recall_explain` log lines). 0 = off; try 0.05 when debugging ranking.
+MINIMA_RECALL_EXPLAIN_SAMPLE=0
 
 # --- Recommender tuning ---
 MINIMA_TAU_MIN=0.55

{minima_cli-0.12.4 → minima_cli-0.13.1}/CHANGELOG.md

@@ -4,6 +4,72 @@ All notable changes to Minima are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.13.1] - 2026-07-21
+
+### Fixed
+- **Plan-mode fallback pool** (TUI, #204): plan mode's premium model-pool
+  restriction only covered the council path — with `MINIMA_TUI_GROUND_TRUTH=0`
+  (or a failed council setup) plan-mode turns ran the normal loop over the full
+  candidate pool, so a cheap/small model could end up doing the planning. The
+  sessionless fallback now routes with the same premium hard pool +
+  `phase:plan` tag as the council's planner turn, with the same loud failure
+  when the policy is active but no premium model is runnable. The restriction
+  is now a property of the mode, not of the council.
+
+## [0.13.0] - 2026-07-21
+
+The Mubit reinforcement train: mubit-sdk 0.13.0 adopted end to end, every free
+signal on the memory wire put to work, and the ground-truth spine's per-step gate
+verdicts start feeding Mubit as process rewards (PRs #192–#197).
+
+### Added
+- **Per-step process rewards** (server + harness, #195): the harness's red→green
+  gate verdicts now ride `POST /v1/feedback` as `step_outcomes[]` and relay to
+  Mubit's `record_step_outcome` — finer-grained reflection attribution and the raw
+  material for server-side workflow induction (procedural memory). Feedback truth
+  applies per step: deterministic/user verdicts only (judge gates excluded),
+  verified/failed only, relayed even on unlabeled turns (steps carry their own
+  provenance), capped at 32, duplicate-feedback check doubles as replay dedup.
+  Response gains `step_outcomes_recorded`.
+- **`POST /v1/diagnose` + `GET /v1/memory/health`** (server, #196): Mubit
+  introspection relays — failure lessons matching an error, and a per-namespace
+  memory-hygiene report (stale entries, contradictions, low-confidence counts,
+  promotion candidates). Both degrade to `memory_unavailable` instead of 500ing.
+  Full client parity (Python sync/async, TS SDK, TUI).
+- **Recovery-ladder memory brief** (TUI, #196): the replan rung asks `/v1/diagnose`
+  for "here's how this failed before" and injects matched lessons into the retry
+  preamble, next to the E2 local diagnostics. Fail-open.
+- **Drift + retrieval signals surfaced** (server, #193): Mubit DriftMonitor flags
+  riding every recall now emit `memory_drift:repeated` / `memory_drift:stagnant`
+  diagnostics, and the server's recall confidence feeds escalation as
+  `low_recall_confidence` (only when reported — absence is not a signal).
+- **Sampled retrieval observability** (server, #194): `MINIMA_RECALL_EXPLAIN_SAMPLE`
+  requests Mubit's per-evidence fusion-score breakdown on a sampled fraction of
+  recalls and logs it as `recall_explain` — the "why did memory rank this" tool.
+
+### Fixed
+- **Dereference now shares the recall budget** (server, #193): it was the one read
+  path with no timeout budget — a hung Mubit could stall a recommend for the full
+  30s client timeout.
+- **Supersession folds into staleness** (server, #193): a `superseded_by` entry is
+  treated as stale even when the `is_stale` flag lags the supersession write.
+
+### Changed
+- **mubit-sdk ≥ 0.13.0** (#192): the v0.12.3 keyed-lookup transport shim is deleted
+  in favor of the now-public `Client.lookup`; the TUI's `@mubit-ai/sdk` moves to
+  `^0.13.0` (transport retries now real). All remaining private `_control` handle
+  uses replaced with the typed surface (#194) — recall knobs and `record_outcome`
+  idempotency are first-class SDK parameters now.
+- **Bi-temporal outcome writes** (server, #194): `remember_outcome` passes
+  `occurrence_time` (observation time, not async-ingest landing time). Seeds are
+  deliberately NOT backdated — the seed-vs-live weighting design stands.
+- **Harness memory lane partition** (TUI, #197): harness trace writes stamp
+  `lane=harness`, keeping them explicitly partitioned from the server's typed
+  outcome records. Recall stays unfiltered until unlaned data ages out.
+- Dead `MubitMemory.get_context` surface removed (#193); recall-precision knobs
+  (`entry_types`, `rank_by`, `budget`, `max_age_days`, `explain_sample`) documented
+  in `docs/configuration.md` (#194).
+
 ## [0.12.4] - 2026-07-21
 
 ### Fixed

{minima_cli-0.12.4 → minima_cli-0.13.1}/CLAUDE.md

@@ -87,7 +87,7 @@ Everything external is behind a Protocol so it can be faked in tests. The server
 
 `MinimaAgent.promptRouted(task)` = **route** (`src/minima/router.ts` → `POST /v1/recommend`) → **run** (agent loop in `src/agent/`, streams the model, executes tools, before/afterToolCall hook stacks, abort via AbortSignal) → **judge** (`src/minima/judge.ts`, abstains unless `MINIMA_LLM_JUDGE=1`) → **feed back** (`POST /v1/feedback` with realized cost). Layers: `src/ai/` (multi-provider LLM API + `faux` test provider) · `src/agent/` (loop, tools, hooks) · `src/minima/` (router, runtime, meter, budget, spawn/sub-agents, ground truth) · `src/tools/` (bash/edit/read/write/grep/todowrite/websearch…) · `src/tui/` (Ink app) · `src/db/` (SQLite spine).
 
-**Ground-Truth verification spine** (shipped 2026-07, `docs/ground-truth-build-guide.md`): **ON by default** since Phase 0b (opt out with `MINIMA_TUI_GROUND_TRUTH=0`). Plan steps carry `verify` shell commands, the harness runs them (baseline → done-gate red→green), verdicts land in the `gates` ledger (migrations v3–v5), a confidence tier drives the UI (🟢 glide / 🟡 flag / 🔴 stop), and grounded outcomes stamp `routing_decisions` for deterministic-over-judge feedback. Green-tier gate verdicts are the harness's honest label source (`evidence_source="gate"` — the only origin that may claim verified-in-production); a sampled LLM judge (`MINIMA_JUDGE_SAMPLE`, default 15% of ungated turns, `MINIMA_LLM_JUDGE=0` disables) labels the rest; everything else is cost/latency telemetry. `/plan` (planner persona + design council + `GROUND_TRUTH.md` output) is part of this spine. Anything gated on ground truth belongs behind `config.groundTruth`, never behind prompt text.
+**Ground-Truth verification spine** (shipped 2026-07, `docs/ground-truth-build-guide.md`): **ON by default** since Phase 0b (opt out with `MINIMA_TUI_GROUND_TRUTH=0`). Plan steps carry `verify` shell commands, the harness runs them (baseline → done-gate red→green), verdicts land in the `gates` ledger (migrations v3–v5), a confidence tier drives the UI (🟢 glide / 🟡 flag / 🔴 stop), and grounded outcomes stamp `routing_decisions` for deterministic-over-judge feedback. Green-tier gate verdicts are the harness's honest label source (`evidence_source="gate"` — the only origin that may claim verified-in-production); a sampled LLM judge (`MINIMA_JUDGE_SAMPLE`, default 15% of ungated turns; `MINIMA_JUDGE_SAMPLE=0` disables, `MINIMA_LLM_JUDGE=1` forces every turn) labels the rest; everything else is cost/latency telemetry. `/plan` (planner persona + design council + `GROUND_TRUTH.md` output) is part of this spine. Anything gated on ground truth belongs behind `config.groundTruth`, never behind prompt text.
 
 **Memory ledger** (Track B of the memory spine, default ON; opt out with `MINIMA_TUI_MEMORY=0`): curated cross-session memory in SQLite (`memories`/`memory_events`/`memory_jobs`, migration v12). Active + pinned rows project into each turn's system prompt for the lead agent only (hard char cap, ranked pinned > gate-cited > recency; every distinct injected set is audited as an `inject` memory_event so "what the model saw" is replayable). Managed via `/memory` (list · add · pin/confirm/reject · delete = bi-temporal invalidate, never DELETE). Only the harness/user writes memories — the model has **no memory-write tool** (Letta split); keep it that way. The **scribe** (`src/minima/memory_scribe.ts`) is the sole automated writer: a background curator fed by SQL over the ledger (gate flips, verified failures, user corrections, judge/gate disagreements — never the transcript), recurrence-gated (a pattern must recur before it earns the one LLM extraction call, which routes through Minima with `tags=["memory:extract"]` and books its spend like judge spend), reconciled mem0-style (ADD/UPDATE/NOOP; rejected rows never resurrected), and provenance-gated (only gate-cited candidates auto-activate; the rest await `/memory confirm`). Triggers (session end, 90s quiet timer, startup leftovers) only enqueue `memory_jobs` rows; a crash-safe drain runs them.
 

{minima_cli-0.12.4 → minima_cli-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minima-cli
-Version: 0.12.4
+Version: 0.13.1
 Summary: Minima CLI: cost-aware LLM model routing — recommend cheaper models, backed by Mubit memory.
 Project-URL: Homepage, https://docs.minima.sh
 Project-URL: Documentation, https://docs.minima.sh
@@ -21,7 +21,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Requires-Dist: anyio>=4.4
 Requires-Dist: httpx>=0.27
-Requires-Dist: mubit-sdk>=0.10.0
+Requires-Dist: mubit-sdk>=0.13.0
 Requires-Dist: pydantic-settings>=2.3
 Requires-Dist: pydantic>=2.7
 Requires-Dist: structlog>=24.1

{minima_cli-0.12.4 → minima_cli-0.13.1}/client_sdk/minima_client/client.py

@@ -18,6 +18,7 @@ from tenacity import (
 from minima.schemas.capabilities import CapabilitiesResponse
 from minima.schemas.common import Constraints, OutcomeLabel, TaskInput
 from minima.schemas.feedback import FeedbackRequest, FeedbackResponse
+from minima.schemas.insight import DiagnoseRequest, DiagnoseResponse, MemoryHealthResponse
 from minima.schemas.models_catalog import ModelsResponse
 from minima.schemas.recommend import RecommendRequest, RecommendResponse
 from minima.schemas.savings import CalibrationResponse, PolicyValueResponse, SavingsResponse
@@ -273,6 +274,38 @@ class MinimaClient:
         raise_for_status(resp)
         return StrategiesResponse.model_validate(resp.json())
 
+    def diagnose(
+        self,
+        error_text: str,
+        *,
+        error_type: str | None = None,
+        limit: int = 5,
+        namespace: str | None = None,
+        user_id: str | None = None,
+    ) -> DiagnoseResponse:
+        """Failure lessons matching an error — 'here's how this failed before'."""
+        req = DiagnoseRequest(
+            error_text=error_text,
+            error_type=error_type,
+            limit=limit,
+            namespace=namespace,
+            user_id=user_id,
+        )
+        resp = self._client.post("/v1/diagnose", json=req.model_dump(exclude_none=True))
+        raise_for_status(resp)
+        return DiagnoseResponse.model_validate(resp.json())
+
+    def memory_health(
+        self, namespace: str | None = None, stale_threshold_days: int = 30
+    ) -> MemoryHealthResponse:
+        """Per-namespace memory hygiene: staleness, contradictions, promotion candidates."""
+        params: dict[str, Any] = {"stale_threshold_days": stale_threshold_days}
+        if namespace is not None:
+            params["namespace"] = namespace
+        resp = self._client.get("/v1/memory/health", params=params)
+        raise_for_status(resp)
+        return MemoryHealthResponse.model_validate(resp.json())
+
     def capabilities(self) -> CapabilitiesResponse:
         resp = self._client.get("/v1/capabilities")
         raise_for_status(resp)
@@ -432,6 +465,38 @@ class AsyncMinimaClient:
         raise_for_status(resp)
         return ModelsResponse.model_validate(resp.json())
 
+    async def diagnose(
+        self,
+        error_text: str,
+        *,
+        error_type: str | None = None,
+        limit: int = 5,
+        namespace: str | None = None,
+        user_id: str | None = None,
+    ) -> DiagnoseResponse:
+        """Failure lessons matching an error — 'here's how this failed before'."""
+        req = DiagnoseRequest(
+            error_text=error_text,
+            error_type=error_type,
+            limit=limit,
+            namespace=namespace,
+            user_id=user_id,
+        )
+        resp = await self._client.post("/v1/diagnose", json=req.model_dump(exclude_none=True))
+        raise_for_status(resp)
+        return DiagnoseResponse.model_validate(resp.json())
+
+    async def memory_health(
+        self, namespace: str | None = None, stale_threshold_days: int = 30
+    ) -> MemoryHealthResponse:
+        """Per-namespace memory hygiene: staleness, contradictions, promotion candidates."""
+        params: dict[str, Any] = {"stale_threshold_days": stale_threshold_days}
+        if namespace is not None:
+            params["namespace"] = namespace
+        resp = await self._client.get("/v1/memory/health", params=params)
+        raise_for_status(resp)
+        return MemoryHealthResponse.model_validate(resp.json())
+
     async def capabilities(self) -> CapabilitiesResponse:
         resp = await self._client.get("/v1/capabilities")
         raise_for_status(resp)

{minima_cli-0.12.4 → minima_cli-0.13.1}/docs/README.md

@@ -22,6 +22,12 @@ your real LLM call.
   guidance.
 - **[Python Client SDK](client-sdk.md)** — the `minima_client` package: sync/async clients
   and the zero-code `autocapture` intake.
+- **[SDK Architecture](sdk-architecture.md)** — how both SDKs (TypeScript + Python) encode
+  the loop: wire-contract mirroring, retry/error discipline, label honesty, and the
+  known asymmetries between the two.
+- **[Harness Architecture](harness-architecture.md)** — the internal agentic structure of
+  the `minima` CLI (`packages/tui`): the turn lifecycle, hook stacks, sub-agent DAG,
+  budget ledger, recovery ladder, ground-truth spine, memory ledger, and DB spine.
 
 ## Guides
 

{minima_cli-0.12.4 → minima_cli-0.13.1}/docs/agent-core-architecture.md

@@ -13,6 +13,10 @@ poisoning stop (client hardcodes verified_in_production + null-quality successes
 
 # Minima Next-Gen Agent Core — Definitive Architecture
 
+> **Historical proposal (2026-07-02).** Much of this has since shipped, evolved, or been
+> superseded (ground-truth spine, memory ledger, recovery ladder). For the architecture
+> as actually implemented, see [harness-architecture.md](harness-architecture.md).
+
 Status: implementation-ready. Branch: `tui-rewrite`. All seams below verified against source at `/Users/shankhadutta/code/costit/packages/tui/src`. Every "already exists" claim that the adversarial reviews contradicted has been corrected in place; where a design asserted a no-op that is actually a real API change, it is flagged as **[API CHANGE]**.
 
 ---

{minima_cli-0.12.4 → minima_cli-0.13.1}/docs/api-reference.md

@@ -213,12 +213,18 @@ rescaled cost-basis tiers.
 | `recommendation_id` | string | required | From a prior `/recommend` (or a step). |
 | `chosen_model_id` | string | required | The model you **actually ran** (may differ from the recommendation; the right model's neighbors are credited). |
 | `outcome` | enum | required | `success` \| `partial` \| `failure`. |
-| `quality_score` | float `0–1` \| null | `null` | Caller-supplied; there is no LLM judge. Defaults applied per outcome if omitted (0.9 / 0.5 / 0.1). |
+| `quality_score` | float `0–1` \| null | `null` | Caller-supplied judge/eval score. Omitted stays `null` (no fabricated default). A score contradicting the outcome label is clamped with a `quality_outcome_mismatch` warning. |
+| `evidence_source` | enum \| null | `null` | Label provenance: `gate` (deterministic check — the only origin that may claim verified-in-production) \| `judge` \| `human` \| `none` (telemetry only; never teaches the success posterior). |
+| `error_cause` | enum \| null | `null` | For failures: `infra` (429/5xx/timeout — never learned as model quality) \| `quality`. |
 | `input_tokens` | int ≥ 0 \| null | `null` | Realized input tokens — **populate this** to enable the rescaled cost tier. |
 | `output_tokens` | int ≥ 0 \| null | `null` | Realized output tokens (captures reasoning/thinking) — **populate this** for the rescaled tier. |
 | `actual_cost_usd` | float ≥ 0 \| null | `null` | Realized $/call — enables the observed cost tier. |
 | `latency_ms` | int ≥ 0 \| null | `null` | |
-| `verified_in_production` | bool | `false` | Marks a real production outcome; gates lesson promotion. |
+| `iterations` | int ≥ 0 \| null | `null` | Agent-loop turns to resolution. |
+| `chosen_effort` | string \| null | `null` | Reasoning-effort level actually used, if varied. |
+| `step_outcomes` | `StepOutcome[]` | `[]` | Per-step verdicts for multi-step work (cap 32/call): `{step_id, step_name?, outcome, signal? [-1,1], rationale?, directive_hint?}`. |
+| `verified_in_production` | bool | `false` | DEPRECATED — send `evidence_source="gate"` instead. |
+| `judged` | bool \| null | `null` | DEPRECATED — send `evidence_source` instead. |
 | `notes` | string \| null | `null` | |
 | `idempotency_key` | string \| null | `null` | Dedupe key; derived from `recommendation_id + model` if omitted. |
 
@@ -232,7 +238,8 @@ rescaled cost-basis tiers.
 | `updated_confidence` | float \| null | Mubit's updated `knowledge_confidence` for the primary entry. |
 | `reflection_triggered` | bool | Whether reflection fired this call. |
 | `lesson_promoted` | bool | Whether a durable lesson was promoted. |
-| `warnings` | string[] | `unknown_recommendation`, `memory_write_failed`, `reinforcement_failed`, `lesson_promotion_failed`. |
+| `step_outcomes_recorded` | int | How many `step_outcomes` were relayed to memory. |
+| `warnings` | string[] | `unknown_recommendation`, `memory_write_failed`, `reinforcement_failed`, `lesson_promotion_failed`, `quality_outcome_mismatch`, `late_feedback_no_attribution`, `step_outcomes_capped:<n>`, `step_outcomes_partial`. |
 
 ### Example
 
@@ -242,8 +249,8 @@ curl -s http://localhost:8080/v1/feedback -H 'content-type: application/json' -d
   "chosen_model_id": "claude-haiku-4-5",
   "outcome": "success",
   "quality_score": 0.95,
-  "input_tokens": 180, "output_tokens": 640, "actual_cost_usd": 0.0034,
-  "verified_in_production": true
+  "evidence_source": "gate",
+  "input_tokens": 180, "output_tokens": 640, "actual_cost_usd": 0.0034
 }' | jq
 ```
 
@@ -309,6 +316,66 @@ dominant_lesson_type, dominant_scope, lesson_ids[]`.
 
 ---
 
+## `GET /v1/savings` · `GET /v1/calibration` · `GET /v1/policy-value`
+
+The measurement layer over your account's decision ledger:
+
+- **`/v1/savings`** (`namespace?`, `days=30`, `group_by=cluster|task_type|lane`) — estimated **and** realized savings against two explicit baselines: `vs premium` (most expensive scored candidate; generous) and `vs declared` (your `baseline_model_id`; honest). `health.feedback_coverage` tells you how much weight the realized figures can bear.
+- **`/v1/calibration`** (`namespace?`, `days=30`) — per-task-type expected calibration error (`ece`, `ece_shrunk`) of `predicted_success` vs realized outcomes, plus sustained drift flags per `(cluster, model)`.
+- **`/v1/policy-value`** (`namespace?`, `days=30`) — doubly-robust off-policy estimates (`RegretReport`): per-policy value, `regret_vs_oracle`, with `stochastic_share` and `n_trusted` surfaced so the number can't overclaim.
+
+---
+
+## `GET /v1/capabilities`
+
+Feature handshake (no auth): `{ plan, workflow, api_version, honored_constraints[] }`. Read once at startup and gate optional features on what the server actually supports.
+
+---
+
+## `POST /v1/diagnose`
+
+Failure lessons matching an error — "here's how this failed before". The harness recovery
+ladder calls this at a verified failure so the retry is briefed by memory. Degrades like
+the recommend hot path (a Mubit outage returns an empty list + `memory_unavailable`, never
+a 500).
+
+### Request — `DiagnoseRequest`
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `error_text` | string (required) | — | The error/failure output to match. |
+| `error_type` | string | — | Optional classifier hint. |
+| `limit` | int `1–25` | `5` | |
+| `namespace` | string | — | Resolves to lane `minima:<namespace>`. |
+| `user_id` | string | — | |
+
+### Response — `DiagnoseResponse`
+
+`{ namespace, lane, failure_lessons: FailureLesson[], summary, total_failure_lessons,
+warnings[] }`, where each `FailureLesson` has `lesson_id, content, lesson_type,
+importance, confidence`.
+
+---
+
+## `GET /v1/memory/health`
+
+Per-namespace memory hygiene: entry counts, stale entries, contradictions, low-confidence
+counts, promotion candidates. Same graceful degradation as `/v1/diagnose`.
+
+### Query parameters
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `namespace` | string | — | Resolves to lane `minima:<namespace>`. |
+| `stale_threshold_days` | int `1–365` | `30` | |
+
+### Response — `MemoryHealthResponse`
+
+`{ namespace, lane, entry_counts: {type: count}, stale_entries, contradictions,
+low_confidence_count, promotion_candidates, section_health, warnings[] }`.
+
+---
+
 ## `GET /v1/health`
 
 Always returns `200`; reports degraded state in the body. Never requires auth (in

{minima_cli-0.12.4 → minima_cli-0.13.1}/docs/configuration.md

@@ -21,6 +21,11 @@ single-tenant mode). A complete annotated template ships as
 | `MINIMA_MEMORY_RECALL_TIMEOUT_MS` | `2500` | Hard recall timeout; on breach, prior-only. Latency is embedder-bound (~100–300ms GPU, ~1.5s local CPU). |
 | `MINIMA_MEMORY_RECALL_LIMIT` | `25` | Max neighbors recalled per request. |
 | `MINIMA_RECALL_MODE` | `agent_routed` | `agent_routed` \| `direct_bypass` (faster but requires `enable_direct_search=true` on the Mubit instance — off by default on hosted Mubit). |
+| `MINIMA_RECALL_ENTRY_TYPES` | `fact,observation` | Server-side entry-type filter (seeds land as `fact`, feedback as `observation`). Empty = no filter. |
+| `MINIMA_RECALL_RANK_BY` | `balanced` | Mubit fusion strategy: `relevance` \| `freshness` \| `balanced` (empty = server default). |
+| `MINIMA_RECALL_BUDGET` | `mid` | Mubit search budget tier: `low` (<500ms) \| `mid` \| `high` (empty = server default). |
+| `MINIMA_RECALL_MAX_AGE_DAYS` | `0` | Hard recency window on recall (`min_timestamp`); `0` = no window. |
+| `MINIMA_RECALL_EXPLAIN_SAMPLE` | `0` | Fraction of recalls (0..1) that request + log Mubit's per-evidence fusion-score breakdown (`recall_explain` log lines). |
 | `MINIMA_LANE_PREFIX` | `minima` | Lane prefix; lane = `<prefix>:<namespace or "default">`. |
 | `MINIMA_SEED_LANE` | `minima:default` | Default lane for `minima-seed`. |