codna 0.1.0__py3-none-any.whl

codna/__init__.py

@@ -0,0 +1,8 @@
+"""Codna — the agent that understands and fixes your repository.
+
+Codna is the user-facing product: the agent head + the Algenta engine behind it.
+This package is the `codna` CLI. Users never touch "algenta" directly — the engine
+is an internal dependency reached over HTTP.
+"""
+
+__version__ = "0.1.0"

codna/_wheel_guard.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+MANIFEST_NAME = "manifest.json"
+KERNEL_GLOB = "libame_kernel.*"
+
+
+def package_runtime_dir() -> Path:
+    return Path(__file__).resolve().parent / "_telys_runtime"
+
+
+def staged_runtime_files(runtime_dir: Path) -> tuple[Path | None, tuple[Path, ...]]:
+    manifest = runtime_dir / MANIFEST_NAME
+    kernels = tuple(sorted(runtime_dir.glob(KERNEL_GLOB))) if runtime_dir.is_dir() else ()
+    return (manifest if manifest.exists() else None), kernels
+
+
+def requires_platform_wheel(runtime_dir: Path) -> bool:
+    manifest, kernels = staged_runtime_files(runtime_dir)
+    return manifest is not None or bool(kernels)
+
+
+def validate_wheel_filename(wheel_name: str, runtime_dir: Path) -> None:
+    if requires_platform_wheel(runtime_dir) and wheel_name.endswith("-py3-none-any.whl"):
+        raise ValueError(
+            "native Telys package-runtime artifacts require a platform-specific wheel tag"
+        )

codna/admission_control.py

@@ -0,0 +1,275 @@
+"""MC-predictive admission control for parallel Codna fixes.
+
+A fix's wall-clock is dominated by the agent + model calls; running too many at once makes every
+in-flight fix share the model's throughput, so the slow tail blows past the SLA (the rust/clap
+>900s timeouts we measured). A static concurrency cap can't see that — it admits a fix that will
+miss the SLA, or it idles capacity that's actually free.
+
+This admitter governs concurrency *predictively*:
+
+  1. Deterministic floor: admit freely up to ``det_cap = min(ceiling, model_rate_budget)`` — clearly
+     safe, no prediction needed.
+  2. Hard ceiling: never exceed ``ceiling`` (the sidecar's AGENT_CORE_MAX_CONCURRENCY).
+  3. MC zone (between det_cap and ceiling): run a Monte-Carlo over the observed fix-duration
+     distribution under the contention the new fix would create, and admit only while
+     ``P(new fix breaches the SLA) < breach_threshold``.
+
+This is Algenta's own Monte-Carlo discipline applied to its own concurrency. The breach predictor is
+**pluggable** (``mc_fn``), with two strategies — both fully LOCAL, ZERO network round-trip:
+
+  • **mojo kernel (default)** — Algenta's compiled ``monte_carlo`` kernel makes the decision, reached
+    through the LOCAL SDK exactly like every fix step (``POST /v1/simulate`` → the loopback daemon, a
+    kernel memory copy on 127.0.0.1, no NIC, no egress). It fits a lognormal to the observed durations
+    (shifted by the contention factor) with objective ``sla - duration`` and reads back
+    ``metrics.probability_of_loss`` ( == P(duration > sla) ) — verified against the live kernel. This
+    is the "mojo decides, in real time" design: the same native engine that governs each fix also
+    governs how many fixes run at once. (The predictor only runs in the contended zone — det_cap < n ≤
+    ceiling; single / low concurrency is admitted at the deterministic floor outright.)
+  • **numpy in-process (fallback)** — an empirical bootstrap over the same observed durations, used
+    automatically if the kernel isn't reachable yet (daemon still warming up) and as the explicit
+    choice via ``CODNA_ADMISSION_MC=numpy``. So the gate can NEVER stall: a kernel hiccup degrades to
+    in-process math, it does not block admission.
+
+Thread-safe: a single lock guards the in-flight counter + the duration window, so it can front a
+thread-pool of fixes.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import Callable
+
+try:
+    import numpy as _np
+except Exception:  # noqa: BLE001 — numpy optional; pure-Python fallback below
+    _np = None
+
+
+# A breach predictor: P(a fix admitted under this contention exceeds the SLA), given the observed
+# duration window, the contention factor, the SLA, and the draw count. Strategies below.
+BreachFn = Callable[[list[float], float, float, int], float]
+
+
+def _numpy_breach_probability(durations: list[float], contention: float, sla: float, n: int) -> float:
+    """Default in-process predictor: empirical bootstrap. Draw base durations from the observed
+    distribution and inflate by the contention factor (fixes share the model rate budget, so each
+    one's wall-clock stretches by ``concurrency / det_cap``). Sub-millisecond, zero network."""
+    if not durations:
+        return 1.0
+    if _np is not None:
+        base = _np.asarray(durations, dtype="float64")
+        draws = _np.random.choice(base, size=n, replace=True) * contention
+        return float((draws > sla).mean())
+    import random
+
+    breaches = sum(1 for _ in range(n) if random.choice(durations) * contention > sla)
+    return breaches / n
+
+
+def mojo_breach_probability(
+    durations: list[float], contention: float, sla: float, n: int, *, client: object | None = None
+) -> float:
+    """Opt-in predictor backed by the engine's compiled ``monte_carlo`` mojo kernel.
+
+    Fits a lognormal to the observed durations (μ = mean(ln d) + ln(contention), σ = stdev(ln d) — a
+    constant scale on a lognormal is an additive shift on μ, matching the numpy path's
+    ``× contention``) and drives ``POST /v1/simulate`` (expert mode) with objective ``sla - duration``.
+    The kernel returns ``metrics.probability_of_loss`` = P(sla - duration < 0) = P(duration > sla) =
+    the breach probability — verified against the live kernel.
+
+    Reached over the LOCAL SDK (loopback daemon, zero network) — the same channel every fix step uses.
+    Raises on any transport/shape error so the caller can fall back to in-process numpy."""
+    import math
+    import statistics
+
+    logs = [math.log(d) for d in durations if d > 0]
+    if not logs:
+        return 1.0
+    mu = statistics.fmean(logs) + math.log(max(contention, 1e-9))
+    sigma = max(statistics.pstdev(logs) if len(logs) > 1 else 0.25, 1e-3)
+    body = {
+        "mode": "expert",
+        "simulation_model": "monte_carlo",
+        "simulation": {
+            "variables": [{"name": "duration", "distribution": "lognormal", "params": {"mean": mu, "std": sigma}}],
+            "objective_function": f"{float(sla)} - duration",
+        },
+        "runs": int(min(max(n, 100), 1_000_000)),
+        "seed": 7,  # deterministic: the window already moves, so a fixed seed keeps the estimate reproducible
+    }
+    if client is None:
+        from codna.cli import _client as _mk
+
+        client = _mk()
+    resp = client._request("POST", "/v1/simulate", json=body)
+    return float(resp["metrics"]["probability_of_loss"])
+
+
+def make_mojo_breach_fn(client: object | None = None, *, fallback: BreachFn = _numpy_breach_probability) -> BreachFn:
+    """Build a ``BreachFn`` that routes to the mojo kernel, falling back to ``fallback`` (numpy by
+    default) on any error so a predictor/engine outage never stalls admission."""
+
+    def _fn(durations: list[float], contention: float, sla: float, n: int) -> float:
+        try:
+            return mojo_breach_probability(durations, contention, sla, n, client=client)
+        except Exception:  # noqa: BLE001 — never let the predictor block the gate
+            return fallback(durations, contention, sla, n)
+
+    return _fn
+
+
+@dataclass
+class AdmissionConfig:
+    ceiling: int = 8                 # hard max concurrency (== sidecar AGENT_CORE_MAX_CONCURRENCY)
+    model_rate_budget: int = 8       # concurrent model calls the provider rate-limit comfortably allows
+    sla_s: float = 900.0             # per-fix wall-clock budget (the timeout)
+    breach_threshold: float = 0.10   # admit in the MC zone only while P(SLA breach) < this
+    trials: int = 4000               # MC draws
+    window: int = 200                # observed-duration ring size
+
+
+@dataclass
+class AdmissionVerdict:
+    admit: bool
+    reason: str
+    in_flight: int
+    det_cap: int
+    p_breach: float | None = None
+
+
+class MCAdmissionDecider:
+    def __init__(self, config: AdmissionConfig | None = None, mc_fn: BreachFn | None = None) -> None:
+        self.cfg = config or AdmissionConfig()
+        # The breach predictor. None → in-process numpy bootstrap; pass make_mojo_breach_fn() to let
+        # Algenta's compiled kernel decide (it already falls back to numpy if the daemon isn't up).
+        self._mc_fn: BreachFn = mc_fn or _numpy_breach_probability
+        self._lock = threading.Lock()
+        self._in_flight = 0
+        self._durations: deque[float] = deque(maxlen=self.cfg.window)
+        self._arrivals: deque[float] = deque(maxlen=self.cfg.window)
+
+    # ── lifecycle the orchestrator calls around each fix ────────────────────────────────────────
+    def start(self) -> None:
+        with self._lock:
+            self._in_flight += 1
+            self._arrivals.append(time.monotonic())
+
+    def finish(self, duration_s: float) -> None:
+        with self._lock:
+            self._in_flight = max(0, self._in_flight - 1)
+            if duration_s > 0:
+                self._durations.append(float(duration_s))
+
+    @property
+    def in_flight(self) -> int:
+        with self._lock:
+            return self._in_flight
+
+    # ── the decision ────────────────────────────────────────────────────────────────────────────
+    def _det_cap(self, model_rate_budget: int | None) -> int:
+        cfg = self.cfg
+        return max(1, min(cfg.ceiling, model_rate_budget if model_rate_budget is not None else cfg.model_rate_budget))
+
+    def _decide(self, inflight: int, durations: list[float], det_cap: int) -> AdmissionVerdict:
+        cfg = self.cfg
+        prospective = inflight + 1
+        if prospective <= det_cap:
+            return AdmissionVerdict(True, "within deterministic capacity", inflight, det_cap)
+        if prospective > cfg.ceiling:
+            return AdmissionVerdict(False, "at hard ceiling", inflight, det_cap)
+        if not durations:
+            # No history yet in the MC zone — be conservative: hold at the deterministic floor.
+            return AdmissionVerdict(False, "no duration history; holding at det_cap", inflight, det_cap)
+        p = self._mc_breach_probability(durations, concurrency=prospective, det_cap=det_cap)
+        if p < cfg.breach_threshold:
+            return AdmissionVerdict(True, f"MC admit (P breach {p:.2f} < {cfg.breach_threshold})", inflight, det_cap, p)
+        return AdmissionVerdict(False, f"MC throttle (P breach {p:.2f} >= {cfg.breach_threshold})", inflight, det_cap, p)
+
+    def can_admit(self, model_rate_budget: int | None = None) -> AdmissionVerdict:
+        """Non-reserving PEEK at the decision (inspection/metrics). To actually take a slot use
+        try_admit()/gate() — they check-and-reserve atomically, avoiding the admit/start race."""
+        det_cap = self._det_cap(model_rate_budget)
+        with self._lock:
+            return self._decide(self._in_flight, list(self._durations), det_cap)
+
+    def try_admit(self, model_rate_budget: int | None = None) -> AdmissionVerdict:
+        """Atomic check-and-reserve: the in-flight slot is taken under the SAME lock as the capacity
+        check, so concurrent callers can't all pass the check before any increments. Pair with
+        finish(duration) when the fix completes (gate() does both)."""
+        det_cap = self._det_cap(model_rate_budget)
+        with self._lock:
+            verdict = self._decide(self._in_flight, list(self._durations), det_cap)
+            if verdict.admit:
+                self._in_flight += 1
+                self._arrivals.append(time.monotonic())
+        return verdict
+
+    def _mc_breach_probability(self, durations: list[float], concurrency: int, det_cap: int) -> float:
+        """P(a fix admitted at this concurrency exceeds the SLA). Contention model: when concurrency
+        exceeds det_cap the shared model throughput stretches each fix's wall-clock by
+        ``concurrency / det_cap`` (fixes share the provider rate budget). The configured predictor
+        (mojo kernel by default, numpy fallback) turns that into a breach probability."""
+        contention = max(1.0, concurrency / det_cap)
+        return self._mc_fn(durations, contention, self.cfg.sla_s, self.cfg.trials)
+
+    def snapshot(self) -> dict:
+        """Lightweight state for metrics/observability."""
+        with self._lock:
+            durs = list(self._durations)
+        return {"in_flight": self._in_flight, "samples": len(durs),
+                "p50_s": (sorted(durs)[len(durs) // 2] if durs else None)}
+
+    @contextlib.contextmanager
+    def gate(self, model_rate_budget: int | None = None, poll_s: float = 1.5, max_wait_s: float = 1800.0):
+        """Wrap a fix: block until admitted (polling the predictive decision), then track the run.
+
+            with decider.gate():
+                run_one_fix()
+
+        Any parallel-fix orchestrator (a batch CLI, the hosted dispatcher, the soak) drops this around
+        each fix; concurrency self-governs to predicted capacity. Raises TimeoutError if never admitted
+        within max_wait_s."""
+        deadline = time.monotonic() + max_wait_s
+        while True:
+            verdict = self.try_admit(model_rate_budget)   # atomic check-and-reserve
+            if verdict.admit:
+                break
+            if time.monotonic() > deadline:
+                raise TimeoutError(f"admission gate timed out: {verdict.reason}")
+            time.sleep(poll_s)
+        started = time.monotonic()
+        try:
+            yield verdict
+        finally:
+            self.finish(time.monotonic() - started)
+
+
+_ADMITTER: MCAdmissionDecider | None = None
+_ADMITTER_LOCK = threading.Lock()
+
+
+def get_admitter() -> MCAdmissionDecider:
+    """Process-wide admitter shared by all concurrent fixes in this process. Tunable via env:
+    CODNA_FIX_CEILING (hard max), CODNA_MODEL_RATE_BUDGET (deterministic floor), CODNA_FIX_SLA_S.
+    Predictor: ``CODNA_ADMISSION_MC`` = ``mojo`` (default — Algenta's compiled kernel via the local
+    SDK, numpy fallback if the daemon isn't up) or ``numpy`` (pure in-process)."""
+    global _ADMITTER
+    if _ADMITTER is None:
+        import os
+        with _ADMITTER_LOCK:
+            if _ADMITTER is None:
+                mc = os.environ.get("CODNA_ADMISSION_MC", "mojo").strip().lower()
+                mc_fn = make_mojo_breach_fn() if mc == "mojo" else _numpy_breach_probability
+                _ADMITTER = MCAdmissionDecider(
+                    AdmissionConfig(
+                        ceiling=int(os.environ.get("CODNA_FIX_CEILING", "8")),
+                        model_rate_budget=int(os.environ.get("CODNA_MODEL_RATE_BUDGET", "4")),
+                        sla_s=float(os.environ.get("CODNA_FIX_SLA_S", "900")),
+                    ),
+                    mc_fn=mc_fn,
+                )
+    return _ADMITTER

codna/agent-core/CLINE_FORK.md

@@ -0,0 +1,55 @@
+# agent-core: forked-Cline vendoring + headless proof
+
+The agent-core sidecar's `runAgent()` (in `run-server.mjs`) is currently a stub. It will be
+backed by a **vendored, Apache-2.0 fork of `@cline/core`** running headless. This note records
+the empirically-verified build recipe and the headless proof so the vendoring step is mechanical.
+
+## Source & license (verified)
+- Upstream: `https://github.com/cline/cline`, Bun monorepo. Spike used HEAD `3a3ea6e`
+  (architecture cross-checked against pinned `1c1ea0bd`).
+- **Root `LICENSE` = Apache-2.0.** BUT `sdk/packages/{core,shared,llms}/package.json` OMIT a
+  `license` field (only `agents` + `sdk` declare `Apache-2.0`). This is why the *npm-published*
+  `@cline/core` reads "Proprietary". **Rule: vendor from the GitHub source (covered by root
+  Apache-2.0), add an explicit `"license": "Apache-2.0"` + header to each vendored package, and
+  NEVER `npm i @cline/*`.** (Release-blocking CI guard = task #4.)
+
+## Build recipe (verified working, Node ≥22 + Bun 1.3.x)
+```sh
+git clone --depth 1 https://github.com/cline/cline.git
+cd cline
+bun install                 # full root install — gets workspace links + tsc (vscode is excluded)
+bun run build:sdk           # = bun --production -F './sdk/packages/*' build  (topological)
+# => sdk/packages/{shared,llms,agents,core,sdk}/dist/index.js all build (exit 0)
+```
+Gotcha: a *filtered* install (`bun install --filter './sdk/packages/*'`) is NOT enough — it omits
+`tsc` and the cross-package workspace links, so the build fails to resolve `@cline/shared`.
+
+The built `core/dist/index.js` **externalizes** its `@cline/*` siblings, so a consumer must have
+them resolvable. In a plain dir, symlink them:
+```sh
+mkdir -p node_modules/@cline
+for p in shared llms agents core sdk; do ln -sfn <repo>/sdk/packages/$p node_modules/@cline/$p; done
+```
+
+## Headless instantiation — PROVEN
+```js
+import { ClineCore } from "@cline/core";
+const cline = await ClineCore.create({ clientName: "algenta-spike", backendMode: "local" });
+// backendMode "local" => in-process LocalRuntimeHost, NO hub daemon, no model, no network.
+// instance API: start, subscribe, restore, disposeSessionBootstrap ; cleanup via dispose().
+await cline.dispose();
+```
+`ClineCoreOptions` (`sdk/packages/core/src/cline-core/types.ts`): `clientName?`, `backendMode?:
+RuntimeHostMode("auto"|"local"|"hub"|"remote")`, `hub?`, `remote?`, `capabilities?`, `prepare?`.
+
+## Next (wire the real adapter — replaces the stub `runAgent`)
+1. Vendor `sdk/packages/{shared,llms,agents,core}` into this fork at a pinned tag (+ Apache headers,
+   strip `shared/src/runtime/cline-environment.ts` + `core/src/services/telemetry/core-events.ts`).
+2. `cline-adapter.ts`: wrap `ClineCore.create({backendMode:"local", capabilities})` + `start()`.
+   - Inject our evidence bundle / blast-radius via the **`capabilities`** option (the verified
+     injection seam — NOT the dead `runtimePlaceholders` path).
+   - Suppress exploration tools at the capability/tool-roster layer (SDK tool names are
+     `bash/editor/read_files/apply_patch/search/fetch_web`, not the classic VS Code names).
+   - Point `@cline/llms` at the loopback OpenAI-compatible model proxy.
+3. Stream `start()` events to the NDJSON `/run` response; agent mutates files under `working_dir`;
+   Python still recomputes the authoritative diff.

codna/agent-core/CLINE_SDK_AZ_INTEGRATION_PLAN.md

@@ -0,0 +1,191 @@
+# Cline SDK A–Z Integration Plan — Cline as the head, Algenta as the engine behind
+
+> Status: **proposal for review** (no code yet). Principle: drive the agent loop with the
+> vendored Apache-2.0 Cline SDK end to end; plug the Algenta engine (250-language repo
+> intelligence + the Mojo decision engine + the capability plane) **behind** it as tools,
+> hooks, and MCP — not a re-implementation. Boundary stays self-hosted HTTP
+> (see `project_sdk_transport_boundary`): Cline (Node head) calls the Algenta engine over
+> the local `/v1/repositories` + capability-plane API; no cloud.
+
+## 1. Where we are (honest baseline)
+
+- **Vendored SDK present:** `agent-core/vendor/cline/sdk/packages/{core,llms,shared,agents,sdk}` (real `@cline/core`, `@cline/llms`, `@cline/shared`, `@cline/agents`).
+- **Adapter written, single-agent slice:** `vendor/cline/algenta/adapter.ts` correctly does `ClineCore.create({backendMode:"local", toolPolicies}) → start() → send() → dispose()`, resolves provider/model/key via `Llms.getProviderCollection`, extracts `usage` + `filesChanged` from `AgentResult.toolCalls`. Real server `vendor/cline/algenta/run-server.ts` wires `runAgent → POST /run` (run with `bun`).
+- **But the RUNNING path is the stub:** `agent-core/package.json` `"start":"node run-server.mjs"` → `run-server.mjs` is a model-less stub (appends a marker, reports `tokens:0`). `node_modules` not installed; the TS server isn't built. So `verified_agentic` → `ALGENTA_AGENT_CORE_URL` currently hits the **stub**, and G0 arms A/C measure nothing real.
+- **Surface used: ~5%.** No `createTool`, no `subscribe()` streaming, no plugins/hooks, no multi-agent (`enableSpawnAgent`/`enableAgentTeams` = false), no MCP, no sessions/checkpoints, no `getAccumulatedUsage`.
+
+## 2. Full Cline SDK surface (what "A–Z" means) — with exact refs
+
+From `agent-core/CLINE_SDK_INTERFACE.md` (signatures copied from the vendored SDK) + docs:
+
+- **`ClineCore` lifecycle:** `create(options)` · `start(input)` (resolves at *launch*, not completion — `ClineCore.ts:252`) · `send({sessionId,prompt,mode,timeoutMs})` → `AgentResult` (awaits the turn) · `abort` · `stop` · `delete` · `dispose(reason?)`.
+- **Sessions:** `list` · `get` · `readMessages` · **`getAccumulatedUsage(sessionId)`** → `{aggregateUsage:{inputTokens,outputTokens,totalCost}}` (includes subagents, `ClineCore.ts:317`).
+- **Events:** `subscribe(listener,{sessionId?})` → stream of `AgentRuntimeEvent` (`assistant-text-delta`, tool calls, `done` w/ `reason/text/iterations/usage`, `ended`). Subscribe **before** `start()`.
+- **`start().config`:** `providerId, modelId, apiKey, systemPrompt, cwd, workspaceRoot, enableTools, enableSpawnAgent, enableAgentTeams, execution.maxIterations`; `pluginPaths?` to load `AgentPlugin`s from disk.
+- **Tools:** `toolPolicies` (`{ "*":{autoApprove:true}, <tool>:{enabled:false} }`); `capabilities.requestToolApproval`; built-ins (files/editor/apply_patch, shell, search/read/list, web/fetch).
+- **Custom tools:** `createTool({name, description, inputSchema: zod, lifecycle?: {completesRun?:true}, execute})` (`@cline/agents`).
+- **Plugins/Hooks:** `AgentPlugin` (alias of `AgentExtension`), `HookControl` (`@cline/shared`) — pre/post tool + lifecycle hooks.
+- **Providers:** `@cline/llms` `getProviderCollection`, `createHandler`, gateway, `resolveProviderModelCatalogKeys`.
+- **Multi-agent:** parallel `Agent` instances (`run/continue/abort/subscribe/restore/snapshot`) + synthesizer; `enableSpawnAgent`/`enableAgentTeams`.
+- **MCP:** MCP servers exposed as agent tools.
+
+Reference example apps (the patterns we adopt):
+- **code-review-bot** ≈ our autonomous fixer: custom `createTool`s (`add_review_finding`, `submit_review` w/ `completesRun:true`) + event filtering by tool name.
+- **multi-agent:** N specialists in parallel (`Promise.all` + per-agent `subscribe`) → synthesizer.
+- **cli-agent:** `run`/`continue` multi-turn + `createTool` shell + delta streaming.
+
+## 3. The Algenta engine behind Cline (the contracts)
+
+Custom tools run **inside the Node agent-core** and call the Algenta engine over the
+self-hosted HTTP API (`ALGENTA_ENGINE_URL` → the FastAPI `/v1/repositories/*` +
+`/v1/capability-*`). The agent calls Algenta tools instead of blind exploration.
+
+| Cline mechanism | Tool/hook | Algenta engine behind | HTTP |
+|---|---|---|---|
+| `createTool` `localize` | input `{issue, changed_files?}` → bounded evidence bundle (files+symbols+snippets) | 250-lang **triage** | `POST /v1/repositories/{id}/triage` |
+| `createTool` `graph_query` | input `{file?,symbol?}` → dependents/blast-radius | dependency graph | `POST /v1/repositories/{id}/graph-query` |
+| `createTool` `simulate_patch` **`completesRun:true`** | input `{decision_plan_id|patch}` → DecisionEnvelope (recommended_action, confidence, risk) — **gates submission** | **Mojo engine** `0.7.0-mojo-parallel` | `POST /v1/repositories/{id}/simulate` |
+| `AgentPlugin` post-edit hook | after each `editor`/`apply_patch`, run sim + enforce calibrated-risk floor; veto on regression | Mojo sim + policy | same |
+| MCP server | the capability plane as MCP tools (`rt.list_capability_providers/execute_capability`) | capability plane | `/v1/capability-*` |
+| `getAccumulatedUsage` | real token/cost out of every run | — | — |
+
+Tool result shape (NDJSON streamed to Python): `{tool, ok, summary, evidence_ref, tokens?}`.
+`simulate_patch` returns `{recommended_action, confidence, risk, engine_version, execution_ms}`;
+the agent is instructed to call it before `submit_fix` and only submit on `apply_patch`.
+
+### 3.1 Two integration seams (research-confirmed — see `CLINE_SDK_RESEARCH.md`)
+
+Deep research on the real SDK surfaced a **second, cleaner plug point** this plan originally
+missed. There are **two** seams, and we use both:
+
+- **Model seam — `ApiHandler` + `llms.registerHandler("algenta", handler)`** (`@cline/llms`).
+  This is the documented way to add a custom provider: implement an `ApiHandler` and register it.
+  Use it to put **Algenta's model/engine (or a local BYOM model) behind the loop as the provider** —
+  cleaner than tunnelling the model through a tool.
+- **Engine/tool seam — `createTool`** (above): the repo-intelligence **triage** + **Mojo sim** +
+  graph as agent tools, with `completesRun` gating apply.
+
+Build on the documented **`@cline/sdk` / `ClineCore`** surface, **not raw gRPC** — research flagged
+gRPC as not-yet-stable/versioned ("docs coming soon"). `@cline/sdk` is **pre-1.0 (`v0.0.x`)**, so
+pin a vendored version and expect signature churn. Capture real usage with **`getAccumulatedUsage`**.
+
+## 3.5 Deployment & privacy posture — Cline on-prem ⟷ Algenta self-hosted
+
+Cline's on-prem story is the same boundary Algenta already enforces, which is why this
+integration is a fit rather than a compromise:
+
+- **Air-gapped / VPC / on-prem:** Cline deploys inside a VPC, air-gapped, or on-prem.
+  Maps 1:1 to Algenta `ALGENTA_DEPLOYMENT_MODE=self_hosted|air_gapped` (the
+  `self_hosted_private_runtime_without_commercial_plane` entitlement, fail-closed egress).
+- **Client-side execution:** Cline processes code locally — the codebase is never uploaded,
+  cached, or indexed by external servers. Matches "no cloud" (`project_sdk_transport_boundary`):
+  the agent-core head, the Algenta engine, and the Mojo sim all run on the box.
+- **No external training:** prompts/data never train public models — consistent with the
+  private-profile red lines.
+- **BYOM / local models (the air-gapped win):** Cline's `@cline/llms` catalog supports
+  **local runtimes (Ollama, LM Studio)** alongside cloud providers. The adapter already
+  resolves provider/model/key from the catalog, so selecting a local provider gives a
+  **fully air-gapped autonomous fixer**: local model → Cline head → Algenta tools
+  (triage + Mojo sim) → all loopback, zero network. Cloud providers (Anthropic, etc.)
+  remain a config switch for non-air-gapped tiers.
+- **Interfaces:** beyond IDE extensions, Cline exposes a terminal UI, a scriptable **CLI**
+  (CI/CD), and **gRPC** APIs, and supports custom UIs (Slack/Discord/dashboards). Our
+  HTTP/NDJSON `/run` sidecar is one such surface; the CLI/gRPC paths are available for
+  CI-driven `/repositories` runs without standing up the HTTP server.
+- **Enterprise (governance/audit):** centralized infra control + audit trails map onto the
+  capability plane's `audit_events` + the calibrated-risk/provenance gates (Phase 2/3).
+
+**Implication for the plan:** provider selection is parameterized end to end — `localize`
+and `simulate_patch` (the Algenta engine) are provider-agnostic, and the agent's *model*
+is a deployment choice (local BYOM for air-gapped, cloud for managed). G0 should record the
+provider/model so token/cost numbers are attributed per tier.
+
+## 4. Phased plan (file-by-file)
+
+### Phase 0 — Foundation: run the real head + real telemetry
+**Goal:** replace the stub with the real Cline server; capture real usage + stream events.
+- `agent-core/vendor/cline/` — `bun install` + `bun run build` (builds `@cline/*` workspaces). *(verify build succeeds; ~minutes)*
+- `agent-core/package.json` — `"start": "bun vendor/cline/algenta/run-server.ts"` (retire `run-server.mjs` to `run-server.stub.mjs`, kept for offline contract tests).
+- `agent-core/vendor/cline/algenta/run-server.ts` — already wires `runAgent`; add `subscribe()` → forward `assistant-text-delta` + `tool_call`/`tool_result` + `done` as NDJSON frames (streaming, not just final).
+- `agent-core/vendor/cline/algenta/adapter.ts` — switch completion to the **event pattern** (`subscribe` before `start`, resolve on `done`/`ended`); call `getAccumulatedUsage(sessionId)` to fill `usage` authoritatively (don't rely on `send().usage`).
+- `apps/api_server/services/repository_intelligence_agent_core_client.py` — parse streamed NDJSON frames; surface `usage{input,output,totalCost}` + `tool_calls` + `turns` into telemetry (`record_tokens`, `agent_turns`, `agent_tool_calls_by_name`).
+- `agent-core/vendor/cline/algenta/adapter.ts` + env — provider/model from `ALGENTA_AGENT_PROVIDER` / `ALGENTA_AGENT_MODEL` via the `@cline/llms` catalog (default `anthropic`; set `ollama`/`lmstudio` for **air-gapped BYOM**). Provider/model recorded in telemetry.
+- `scripts/g0_token_benchmark.py` — record provider/model per arm so tokens/cost are attributed per tier; once the sidecar is real, arms A/C produce real numbers.
+- **Exit:** real Cline run on a fixture (cloud and a local-BYOM smoke); G0 A vs C with real tokens/turns/resolution (the comparison we owe).
+
+### Phase 1 — Engine behind: Algenta custom tools
+**Goal:** the agent calls Algenta instead of exploring.
+- `agent-core/vendor/cline/algenta/tools/localize.ts` — `createTool` → `POST {ALGENTA_ENGINE_URL}/v1/repositories/{id}/triage`.
+- `agent-core/vendor/cline/algenta/tools/graph_query.ts` — `createTool` → `/graph-query`.
+- `agent-core/vendor/cline/algenta/tools/simulate_patch.ts` — `createTool` `lifecycle:{completesRun:true}` → `/simulate` (Mojo); returns the gate.
+- `agent-core/vendor/cline/algenta/adapter.ts` — register the tools; system prompt: "call `localize` then edit, call `simulate_patch` before finishing; submit only if `recommended_action==apply_patch`."
+- `apps/api_server/services/repository_intelligence_verified_agentic.py` — pass `repository_id` + `ALGENTA_ENGINE_URL` so the tools can call back; keep exploration suppressed (tools replace it).
+- **Exit:** a fix where the agent localizes via triage + verifies via Mojo, with the sim gating submission.
+
+**Pinned attach mechanism (from vendored source — `ClineCore` path).** Custom tools do NOT
+go on `start().config` directly; they attach through an `AgentExtension` (= `AgentPlugin`)
+loaded from disk via `config.pluginPaths`:
+```ts
+// algenta/tools.ts
+import { createTool } from "@cline/sdk"; import { z } from "zod";
+export const localize = createTool({
+  name: "localize", description: "Triage the repo to a bounded evidence bundle.",
+  inputSchema: z.object({ issue: z.string(), changed_files: z.array(z.string()).optional() }),
+  execute: async (i) => httpPost(`${ENGINE}/v1/repositories/${REPO}/triage`, ...),
+});
+export const simulatePatch = createTool({
+  name: "simulate_patch", description: "Verify the patch via the Mojo engine.",
+  inputSchema: z.object({ decision_plan_id: z.string().optional() }),
+  lifecycle: { completesRun: true },                 // Q2: returning don't-apply ENDS the run, no submit
+  execute: async (i) => httpPost(`${ENGINE}/v1/repositories/${REPO}/simulate`, ...),
+});
+// algenta/algenta-plugin.ts
+import type { AgentPlugin } from "@cline/core"; import { localize, simulatePatch, graphQuery } from "./tools";
+const plugin: AgentPlugin = { name: "algenta-engine",
+  setup(api) { api.registerTool(localize); api.registerTool(simulatePatch); api.registerTool(graphQuery); } };
+export default plugin;
+// adapter.ts (start config, only when ENGINE url is set):
+//   pluginPaths: [resolve(__dirname, "algenta-plugin.ts")]
+```
+`createTool` = `{ name, description, inputSchema (Zod|JSON-schema), execute(input, ctx) => Promise, lifecycle?: { completesRun? } }` (shared/tools/create.ts). `AgentExtension.setup(api)` → `api.registerTool(tool)` (plugin-tools.ts:117). Tools call the engine over **loopback HTTP** (Q1) → `ENGINE = ALGENTA_ENGINE_URL`, `REPO` from the run payload. Additive: no `ALGENTA_ENGINE_URL` ⇒ no `pluginPaths` ⇒ current behavior unchanged.
+
+### Phase 2 — Govern + verify: plugins/hooks
+- `agent-core/vendor/cline/algenta/plugins/mojo_gate.ts` — `AgentPlugin` post-`apply_patch` hook → run sim, veto (`HookControl`) if it regresses or breaches the calibrated-risk floor.
+- `agent-core/package.json` start → `pluginPaths` includes the gate.
+- **Exit:** apply is provably sim-gated inside the agent loop (provenance red line holds).
+
+### Phase 3 — Capability plane as MCP
+- Expose `/v1/capability-*` as an MCP server the agent can mount (read-only providers/bindings + `execute_capability` for `client_managed`).
+- **Exit:** the agent can discover/execute governed capabilities through Cline's MCP path.
+
+### Phase 4 — Multi-agent panel (scale)
+- `enableAgentTeams` / parallel `Agent`s: localize · fix · verify specialists → synthesizer (multi-agent example pattern); reconcile to one calibrated decision.
+- **Exit:** harder bugs solved by a panel; still one provenance-gated apply.
+
+## 5. Verification (per phase)
+- **G0 (`scripts/g0_token_benchmark.py`):** A (vanilla explore) vs C (Algenta tools + suppressed exploration) on real Cline — gate **C ≤ 0.25× A tokens, resolution within 5pp**. Report tokens/turns/wall-clock/resolution + expected cost.
+- **Real-repo probe (`benchmarks/repository_intelligence_real_repo_probe.py`):** unchanged for the deterministic pipeline; agentic tier now exercises real Cline.
+- **Contract tests:** keep the hermetic `verified_agentic` test green (stub server retained for offline CI); add a real-server smoke gated on `bun` + key presence (skip when absent, per the integration-test conftest).
+- **Red lines:** calibrated-risk + provenance gates enforced by the Phase-2 hook; Cline attribution internal-only; no cloud egress (self-hosted boundary).
+- **Air-gapped BYOM smoke:** run the full fixer with a local model (Ollama/LM Studio) + `ALGENTA_DEPLOYMENT_MODE=air_gapped`; assert resolution with **zero external network egress** (privacy-guard denies non-loopback) — proves the fully-private autonomous tier.
+
+## 6. Risks / open questions
+- **Build:** `bun run build` of the vendored SDK must succeed on this toolchain (node 23 / bun 1.3.14). If it fails, Phase 0 is blocked — fix before anything else.
+- **Tool callback boundary:** tools call the FastAPI engine over loopback HTTP — needs the api_server running (or an in-process shim for tests). Decide: always-HTTP vs in-process for CI.
+- **`completesRun` semantics:** confirm a `completesRun` tool that returns "do not apply" cleanly ends the run without a bad edit.
+- **Token attribution:** `getAccumulatedUsage.aggregateUsage` includes subagents — use it (not `send().usage`) once multi-agent lands.
+- **Cost:** real LLM calls on every agentic run; keep the G0 suite small + gate live runs behind explicit env.
+
+### Research-grounded caveats (from `CLINE_SDK_RESEARCH.md`, verified 2026-06-10)
+- **Privacy is scoped to Cline-the-vendor.** "Code never leaves / never indexed or cached / not used
+  for training" holds for Cline, but **inference routes to whatever provider you configure**. Three
+  blanket "everything client-side" claims were **refuted 0-3**. **Zero-egress requires BYOM local
+  model (Ollama/LM Studio) or the Algenta engine via `registerHandler`** — design the air-gapped tier
+  around that, not around Cline's posture alone.
+- **`local` backend no-egress contract is unconfirmed** — verify telemetry/licensing/model-catalog
+  refresh can all be disabled before claiming air-gapped.
+- **gRPC unstable + SDK pre-1.0** — embed via `@cline/sdk`/`ClineCore`, pin the version, expect churn.
+- **`ApiHandler` contract not fully extracted** — confirm the streaming/tool-call/usage surface a
+  private engine must implement for `registerHandler` + `getAccumulatedUsage` before Phase 1.
+- **Unverified, do not cite as fact:** the "1M-token context" / "Memory Bank" Cline-vs-Cursor claims
+  did not survive verification.