@calliopelabs/cli 3.6.0 → 3.7.0

package/docs/improvement-cycles.md

@@ -0,0 +1,304 @@
+# Bounded improvement cycles
+
+Version-4 [supervised runs](continuous-supervision.md) record each final `retry`,
+`replan` or `decompose` decision as an improvement cycle. The controller optimizes
+for the reviewed principle (`speed`, `robustness`, `stability`, `security`,
+`performance` or `cost`), reviews executor evidence, and receives the latest four
+cycles' measured outcomes. A reviewer, when configured, owns the final decision;
+its controller draft is not a second improvement.
+
+## Host capability discovery
+
+`calliope improve host-capabilities --contract-version 1 --json` returns the
+additive version-1 `improvement.host-capabilities` contract. It inventories the
+native execution, review-request, task-outcome and source-change interfaces with
+their independent versions. Discovery uses CLI JSON; operations use the native
+library APIs described below. This declaration does not create remote RPC methods.
+Unknown requested versions and run/approval/mutation selectors are refused.
+
+`implementation` identifies the installed package version, artifact form and
+build metadata status. Source metadata records the build's Git commit and dirty
+state when available; builds outside their own source repository retain `null`.
+The query never runs Git in the caller's project. Missing, malformed or mismatched
+metadata cannot establish source identity. Even clean metadata is self-reported:
+verify npm integrity and publisher provenance, or standalone release checksums
+and binary attestations, against the same release tag and source commit before
+trusting it. The query explicitly reports `external-attestation-required`.
+
+Legacy execution discovery remains unchanged:
+
+`calliope improve capabilities --json` returns a version-1 `improvement` envelope
+whose action is `capabilities` and whose data kind is `improvement.capabilities`.
+The data contract is version 2; its `hostAdmission` field advertises the native
+`expectedExecutionRevision` option for propose/run and binding to the controller's
+own committed reset event. Version-1 declarations do not promise this admission
+contract. The outer CLI response envelope remains version 1.
+This read-only query does not select a project/run, call a model, import feedback,
+or grant execution authority. Run selectors, approval hashes and mutation flags
+are rejected for this action. Hosts must negotiate this declaration instead of
+inferring learning support from the package version or command names.
+
+The current declaration advertises native recursive task-strategy improvement,
+history schema versions, operation effects, exact-proposal approval, inherited
+limits and withdrawal semantics. External feedback import, cross-run learned
+strategy selection and model training are explicitly unavailable. Project brain
+memory remains a separate interface. A supported operation still requires the
+exact native run's current state and policy; this declaration is not evidence
+that an installed run can execute it. Unknown contract versions are not compatible
+by implication. This is the capability-discovery part of #413, not a completed
+external feedback or reinforcement-learning interface.
+
+## Host review requests
+
+The separately negotiated `improvementReviewCapabilities()` API (version 1,
+`improvement.review-capabilities`) advertises `requestImprovementReview`,
+`inspectImprovementReviews` and `dismissImprovementReview`. It is request-only;
+existing version-2 execution capabilities are unchanged. Hosts must negotiate
+this API separately before exposing a model request tool. Hosts supply the model-tool and human-review UI adapters. This API increment
+does not add a CLI subcommand.
+
+Requests carry version 1, `action` (`propose`, `run`, `rollback`), the exact
+`executionRevision`, `cycleId` and `proposalHash` (both null for `propose`), and a
+nonempty untrusted `reason` of at most 1,024 characters. Recording requires an
+inactive approved supervised run and native policy/confirmation. It calls no
+model, starts no worker, approves no proposal, and changes neither task state nor
+budget. Run/withdrawal requests bind the native proposal hash; a new proposal
+request needs retained task outcomes and remaining original controller time and
+round capacity. Withdrawal requests can outlive the original deadline.
+
+Version-9 events append to the existing private execution journal. Each request
+is bound to the immediately preceding revision. Only one request can be current;
+identical retries after a lost acknowledgement return that same request ID after
+rechecking policy and run approval. A competing changed request fails. Native
+ownership, revision and revocation checks run again before commit. At most 64
+requests are retained per run, within the existing journal byte/event bounds.
+Replay independently validates requests and never derives execution authority
+from them. Older readers that do not support event version 9 must refuse these
+journals; do not downgrade a run's owner after recording a request.
+
+Inspection projects `pending`, `expired`, `stale` or `dismissed` from native
+events. Any later execution/control event makes the old request stale, not
+approved or completed. Human execution must use a fresh native inspection and
+the existing proposal/run/withdrawal APIs with their normal review and policy.
+Dismissal requires the exact current request ID/revision and a separate native
+confirmation; it retains all history and does not withdraw the strategy. The
+request reason remains untrusted display data, never an instruction or reward.
+
+## Controls
+
+```sh
+calliope improve history --run RUN_ID --json
+calliope improve propose --run RUN_ID --allow-mutations --json
+calliope improve run CYCLE_ID --run RUN_ID --approve PROPOSAL_HASH --allow-mutations --json
+calliope improve rollback CYCLE_ID --run RUN_ID --allow-mutations --json
+```
+
+The REPL exposes the same arguments under `/improve`. Without a subcommand it
+shows history; without `--run` it inspects the latest run in the active project.
+Headless mutations require `--allow-mutations` or an approval callback, and still
+pass project policy. REPL approvals use the existing scope preview and audit log.
+
+`propose` reviews an inactive supervised run's retained outcomes, or returns its
+existing pending proposal without another model call. Explicit recovery of a
+halted controller retains its original rounds, task attempts, reservations and
+deadline. It starts no workers and applies no proposed changes. It needs recorded
+outcomes and remaining controller authority; a completed run or a `continue` or
+`stop` decision can produce no improvement proposal. Inspect that decision before
+resuming ordinary execution.
+
+A recorded proposal hold survives restart. `run` requires its exact review hash;
+ordinary `run resume` cannot bypass that hold. Approval is recorded in the same
+execution journal before application, and checked again under coordinator
+ownership. All subsequent decisions remain subject to the original reviewed
+supervision policy. To inspect and retire a strategy, stop the coordinator first.
+
+Native hosts can pass `expectedExecutionRevision` to `proposeImprovement` and
+`runImprovement`. It must match the execution revision from their reviewed
+inspection. Malformed, missing-history and stale bindings are refused before
+execution approval. The coordinator rechecks after asynchronous authorization,
+under its ownership lease and inside the journal append lock before starting
+work. The execution permission request includes that bound `executionRevision`.
+An explicit controller reset advances the binding only to its own committed
+reset event; another writer's revision is never silently adopted. Existing
+callers that omit the option bind to the history inspected by the improvement
+action. This host API does not add a CLI flag; hosts negotiate the version-2 data
+contract before relying on it. It does not authorize execution, change proposal hashes, or replenish
+the original budget or deadline.
+
+`rollback` **withdraws the execution strategy**. For a replan it restores the
+previous unwithdrawn applied strategy; for decomposition it stops the admitted
+child agents and their descendants. It stops controller continuation and preserves
+the task graph, allocations, attempts, checks, candidate worktrees and artifacts.
+It does not apply an inverse patch to source: this loop edits isolated candidates,
+and never automatically applies them to the source checkout. Inspect the retained
+base commit and patch artifacts to compare or recover a candidate. A different
+pending decision must be resolved before withdrawing an older cycle. Withdrawing
+an expired cycle is allowed because it reduces authority; it cannot revive the
+clock or refund spend.
+
+## Evidence and schema
+
+History is a deterministic projection of the existing private, hash-chained
+journals, not a second mutable database. Legacy histories and cycles retain
+`version: 1`; runs with [request attribution](request-attribution.md) use version 2
+and identify the observed budget revision. Cycles whose review events carry
+sanitized [provider-health evidence](provider-health.md) use version 3 and retain
+the controller snapshot plus the reviewer snapshot when that separate role is
+configured. This records the aggregate operational evidence available to each
+decision without importing credentials, endpoint strings, provider text or new
+execution authority. Each cycle's immutable ID is its final decision event ID. It
+includes:
+
+- Trigger event IDs/hashes, principle, proposed hypothesis/change/metric.
+- Parent decomposition and previous attempt links, target tasks, original run
+  deadline and limits, scoped worker/controller/reviewer accounts and ancestors.
+- Review hold, explicit approval, application and withdrawal event references;
+  original plan approval and separate production approval (`not-approved`).
+- Baseline and direct next-attempt outcomes, checks, artifact hashes, observed
+  duration/tool results, unresolved risks, isolation image and rollback references.
+- Original manifest hash and the inspected execution revision.
+- Controller and optional reviewer provider-health snapshots, their observation
+  times, relevant-event counts and history hashes.
+
+Inspection validates journal ancestry, current artifact read permissions, retained
+artifact bytes and the pinned worktree base. Evidence reads are bounded to 64 MiB
+per inspection; histories retain the execution store's existing event/size bounds.
+No inspection calls a model or replays a tool. Recorded run replay reproduces the
+same cycles without execution. Keep history private: task evidence can contain
+project information even though API keys are not part of the cycle contract.
+
+A cycle measures its **direct next attempts**. If a decomposed child fails and a
+nested replan fixes it, the parent cycle retains that first failed result and the
+nested cycle records the verified retry. This preserves the failure instead of
+retroactively claiming every experiment succeeded. `verified` means the recorded
+targets completed their acceptance process, not that every optimization claim was
+proved. Human acceptance remains distinguishable by its source event.
+
+## Measurements and limitations
+
+| Measurement | Definition | Comparison requirement |
+|---|---|---|
+| `acceptance-check-pass-rate` | Passed recorded acceptance checks / all recorded checks | Same tasks and check definitions |
+| `attempt-duration` | Sum of task-start to task-finish event durations, milliseconds | Same complete task population |
+| `tool-failure-rate` | Failed completed tool calls / completed tool calls | Same complete task population |
+| `provider-accounted-cost` | Accounted provider charges for the recorded worker attempts, integer nano-dollars | Same complete task population, bound request provenance and fully settled usage |
+
+Missing measurements are `null`, never zero. New task populations and changed
+check definitions are explicitly non-comparable. These observations do not prove
+causality or provide an automatic security/performance certification. Requested
+metrics remain proposed even when checks pass. The duration is summed task time,
+not workflow wall time; acceptance checks are not the individual assertions inside
+a test process. The cost measurement excludes planning and controller/reviewer
+overhead, and is not whole-goal cost per successful task or an invoice. Those
+roles retain separate request attribution in run diagnostics. Unknown or pending
+requests retain their conservative charge, but prevent a comparable cost delta.
+Legacy/missing bindings yield unavailable costs rather than fabricated zeroes;
+the shared run/project ledgers continue enforcing their original reservations.
+
+For linked goals, [whole-goal metrics](goal-accounting.md) separately include
+planning and review overhead and inspect final artifacts before reporting cost
+per verified task. This total is not a comparable before/after cycle metric.
+
+The HUD adds the latest cycle's status, comparable check rate and comparable
+worker-attempt cost. Explicit Brain run ingestion cites the budget revision and
+stores a separate snapshot when accounting changes; hypotheses remain proposed.
+Headless output
+uses `version: 1`, `type: improvement` for results and `type: improvement.event`
+for streamed execution events; enclosed events keep their own schema version.
+Execution exit codes remain 0 success, 4 partial, 3 policy denial, 130 cancellation
+and 1 failure; malformed command arguments exit 2. History is local-only JSON and
+can be redirected for diagnostics. There is no import of execution authority.
+
+## Safety and recovery
+
+The loop cannot edit permissions, expand budgets/depth/count, reset deadlines,
+erase evidence, publish, merge, deploy or send external messages. Every file/tool
+mutation uses the shared runtime gates; child admission rechecks inherited scope
+and grants. All coding attempts use retained Git worktrees and reviewed isolated
+verification. Unknown requests retain their reservation, and interrupted calls
+require explicit recovery. A cancelled or denied experiment keeps its partial
+results; a new run is not an automatic escape from its allowance.
+
+This implements recursive, evidence-driven **task strategy improvement**. It does
+not automatically patch Calliope itself or promote knowledge to accepted fact.
+The [project Brain](project-brain.md) can explicitly ingest verified run evidence;
+improvement hypotheses remain proposed. [Opt-in agent retrieval](agent-knowledge.md)
+lets planners and workers read that knowledge within their inherited source scopes.
+
+## Reviewed source proposals
+
+The native `sourceChangeCapabilities`, `previewSourceChange`,
+`proposeSourceChange`, `inspectSourceChange` and `listSourceChanges` APIs let a host offer verified
+source changes for human review. A source-owned skill or interface uses the Git
+repository that owns its files. Installed skills keep their separate installation
+and trust lifecycle.
+
+The selection binds the original run, execution revision, verified cycle, task
+and executor-collected patch hash. Preview checks the original approval, task
+write scope, pinned source commit and repository-local author. It returns the
+patch, affected paths and a review hash without creating Git objects or refs.
+Creating a proposal requires the exact `orchestration_source_proposal` permission
+and rechecks those inputs under the execution lease.
+
+The writer creates one commit and one local branch under
+`refs/heads/calliope-proposals/<run>/<review hash>` using a temporary private
+index. It leaves the source checkout/index and execution journal unchanged.
+Immutable intent and candidate records support retry after cancellation or a lost
+response; repeated publication recovers the same branch instead of overwriting
+it. Inspection reports `prepared` when the branch is absent and `proposed` when
+the exact recorded commit is present. Absence alone does not establish whether
+someone previously removed the branch. A moved branch is a conflict.
+Listing retains original review identities across restart and source HEAD changes;
+it reads the same native intent/candidate records and checks each branch.
+
+This API does not install skills, merge, push, release or invoke a model. A host
+must explicitly support the separate versioned source-change capability before
+offering the action. Desktop integration and platform qualification are separate
+from native API validation.
+
+## Ordinary task evidence
+
+`taskOutcomeCapabilities()` and `inspectTaskOutcome(project, runId, selection,
+options)` expose the same native evidence for an ordinary task outside an
+improvement cycle. Select `{taskId, attempt, executionRevision}` from an inactive
+run. The reader replays the journal at that attempt's start, retains its task,
+agent and strategy configuration hash, and revalidates each artifact's bytes
+under the native read policy. It refuses active ownership, stale selections and
+changed or missing evidence. In particular, a historical live project file that
+a later retry overwrote cannot be freshly verified; retained run artifacts allow
+independent inspection of both attempts.
+
+The returned `{value, hash}` separates executor status from native human task
+acceptance, includes original event/check/artifact references, and attributes
+charges to the exact start event using the reservation ledger. Missing or
+unsettled costs remain `null`; reservations are not reported as settled cost.
+Duration, tool calls and failures are recorded observations. An interrupted
+attempt without a finish remains unknown. The accounting snapshot carries its
+own ledger revision and may advance independently of the execution journal.
+
+This read-only API performs no inference, artifact execution, ledger writes,
+user assessment, feedback import or reward assignment. A host may separately
+propose a human assessment for memory review; doing so does not change the
+executor evidence. Ordinary-task UI and memory feedback require their own host
+qualification.
+
+## Native validation
+
+The [native Brain-loop receipt](docs/evidence/native-brain-loop-smoke.json) records a
+Fable planner/controller and a Haiku worker on a public clamp fixture. All 12 paid
+requests used the native provider after live discovery. Planning recovered from
+one output cutoff within its original allowance. After exact-plan review, the
+worker submitted a deliberately unchanged baseline, the real Docker check failed,
+the controller replanned, and a one-line repair passed the same unchanged tests.
+The live HUD showed both agents, attempts, controller rounds and remaining budgets.
+
+Planner and worker Brain reads left its journal unchanged. A fresh process resumed
+and replayed the completed run without model calls or execution/budget changes.
+Explicit run ingestion then preserved both failed and passed checks as observations
+and the improvement hypothesis as proposed knowledge. All artifact hashes were
+verified, and the source checkout remained unchanged.
+
+The probe retained $3.068752 of conservative reservations, including the cutoff,
+within a $5 cap. This demonstrates one staged repair cycle; it does not establish
+general coding reliability, causal improvement, or native nested decomposition.
+Provider conformance and signing remain separate release gates.

package/docs/releases/3.7.0.md

@@ -0,0 +1,53 @@
+# Calliope CLI 3.7.0
+
+This release adds durable ACP session controls, tightens reviewed inference
+admission, and publishes a versioned discovery contract for native improvement
+hosts. It retains the LiteLLM retirement and Hugging Face support from 3.6.0.
+
+## ACP session controls
+
+ACP clients can change Work/Plan mode through `session/set_mode` and choose a
+model through `session/set_config_option`. Model choices come from live provider
+discovery. Saved controls survive process restart; stale or concurrent updates
+refuse instead of overwriting another client. Plan mode denies mutating tools.
+Delegated sessions retain their parent's model authority.
+
+The stable ACP wire protocol and `--version --json` remain unchanged. Clients
+must negotiate `_meta.calliopeSessionControls.version: 1`; an older CLI does not
+promise these controls. See the [ACP contract](../acp.md).
+
+## Reviewed inference authority
+
+New remote-ledger reservations must match the current admitted agent's explicit
+provider/model choices. The host rechecks those constraints under the ledger
+writer lock, including for newly admitted descendants. Rejected choices leave
+the parent's allowance unchanged; already-admitted requests retain their replay
+and settlement semantics.
+
+The Node and standalone qualifications use real child and ledger processes with
+deterministic local inference. Task/attempt and endpoint authority, Smart routing
+stage binding and actual disposable Astrolift parent/child acceptance remain in
+[#415](https://github.com/calliopeai/calliope-cli/issues/415). This release does not
+claim those deployment requirements are complete.
+
+## Native improvement host discovery
+
+`calliope improve host-capabilities --contract-version 1 --json` reports the
+installed native execution, review-request, task-outcome and source-proposal
+interfaces with independent versions. It does not open the caller's project or
+grant execution authority. Unsupported versions and execution selectors refuse;
+the existing `improve capabilities` response remains compatible.
+
+The declaration includes the installed package version and build source metadata
+when available. Metadata is self-reported, not proof of authenticity: verify npm
+integrity and provenance, or native checksums and attestations, against the release
+tag and source commit. Missing, dirty or invalid metadata cannot establish a
+released build. See the [improvement host contract](../improvement-cycles.md).
+
+External feedback import, cross-run learned strategy selection and model-weight
+training remain unavailable. SDK 7 recapture work remains separate from this
+release; xAI live qualification remains deferred.
+
+Refs: [#444](https://github.com/calliopeai/calliope-cli/issues/444),
+[#415](https://github.com/calliopeai/calliope-cli/issues/415),
+[#413](https://github.com/calliopeai/calliope-cli/issues/413).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calliopelabs/cli",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "The private-AI agent CLI - one terminal agent for any model backend, including the ones you run yourself",
   "keywords": [
     "ai",
@@ -38,10 +38,13 @@
     "docs/migration-*.md",
     "docs/migration-example-*.json",
     "docs/delegation-ledger.md",
+    "docs/improvement-cycles.md",
+    "docs/acp.md",
+    "docs/releases/3.7.0.md",
     "docs/releases/3.6.0.md"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/bin.js",
+    "build": "tsc && node scripts/build-metadata.mjs && chmod +x dist/bin.js",
     "dev": "tsc --watch",
     "start": "node dist/bin.js",
     "test": "vitest run",