git:20260807.5640f5b to git:20260828.c51ac2c

# Framework Agent — Sibling Skill

> **Purpose**: vllm/sglang source-layer optimisation companion for

> `inference_optimizer`. It discovers framework / ref candidates

> (via Primus Cortex + GitHub Search), optionally builds/benchmarks

> them in isolated worktrees, and serves the Coordinator's

> FRAMEWORK_AGENT phase. Exposed through the `fa` / `framework-agent`

> console entry points.

## Layout

This skill lives in the `hyperloom` src-layout distribution:

```

src/hyperloom/agents/framework/ # hyperloom.agents.framework

├── runtime/cli.py # fa schema / candidates / explore / phase-discover / kb

├── runtime/tools_api.py # library API behind the CLI verbs

├── explorer.py # explore loop (libcst-free)

├── isolation.py # per-candidate worktree + venv

├── decision.py # 3-gate winner decision

├── kb.py # knowledge-base operations

├── repo_map.py # framework -> canonical repo URL

├── keywords.py / models.py # request models + keyword helpers

├── logging_setup.py # shared: structured logging

├── sources/ # primus_cortex + github discovery

└── tests/

```

The `fa` CLI ships with the distribution, so there is no separate installer

for this skill: `pip install -e '.[test]'` from the repo root provides it.

The KB a session reads and writes is `INFERENCE_OPTIMIZER_FA_KB_PATH` when

set, else `<workspace>/framework-kb` (`USER_DATA_PATH` or the pod-local

default). It is deliberately not `<workspace>/kb`, the legacy recipe root:

every directory under this root is reported as a framework domain. The

orchestrator's writeback resolves the same root, so both halves move together.

The runtime partition written under it is `framework_optimization/<framework>/`.

Read-only seed data shipped in the wheel lives separately under the package.

## Subcommands

```bash

fa schema # print the request schema summary (debug)

fa candidates --request req.json [--out -] # enumerate PR/ref candidates, no build/bench

fa explore --request req.json [--execute] [--out -] # plan (default) or build/bench loop

fa phase-discover --request req.json [--out -] # Coordinator FRAMEWORK_AGENT phase entry point

fa phase-audit --request req.json [--out -] # static local-source judging of a discovered candidate

fa kb list|show|search|contribute|synthesize ... # knowledge-base ops

```

`fa candidates` / `fa explore` run a standalone investigation loop (no

IO coordinator). `fa phase-discover` is the thin shim driven by the

Coordinator's per-candidate pump in the FRAMEWORK_AGENT phase (between

subcommands (`phase-discover`, `phase-audit`) are the **only** ones

`src/hyperloom/orchestrator/framework/client.py` invokes. Don't use

`phase-discover` outside that context.

## FRAMEWORK_AGENT phase (`fa phase-discover`)

Reads `--request <json>` and writes `--out <json|->` (envelope style

mirrors `hyperloom.agents.critic.runtime.cli`):

```bash

# Discover a batch of PR candidates for the current run's gaps.

# request: {model, framework, gpu_type, gaps[], repo_url?, max_search_candidates, batch_id}

# output: {batch_id, framework, repo_url, candidates: [...]}

fa phase-discover --request req.json --out -

```

## FRAMEWORK semantic audit (`fa phase-audit`)

Given a discovered candidate + the live framework source roots, decide whether

the PR's change is already present locally so the Coordinator can skip

already-merged PRs and seed the authoring specialist with evidence:

```bash

# request: {candidate, framework, framework_source_roots[],

# diff_text|patches_path|primus_cortex_url, work_dir?, use_llm?, model?}

# output: {candidate_id, semantic_status, applicability, confidence,

# evidence[], risks[], recommended_next_step, layer, metrics}

fa phase-audit --request req.json --out -

```

- **static layer (default, hermetic)**: parse the diff, resolve each touched

file under `framework_source_roots`, measure added-line / symbol presence +

context-anchor presence.

- `semantic_status` ∈ `already_equivalent` / `already_superset` /

`partially_present` / `not_present` / `unknown`.

- `applicability` ∈ `direct_apply` / `needs_rewrite` / `not_applicable` /

`needs_human_review`; `recommended_next_step` ∈ `skip` /

`direct_framework` / `author_via_specialist`.

- `already_*` is evidence-gated (downgraded to `unknown` without a concrete

symbol/line hit).

- **llm layer (opt-in, `use_llm=true`)**: single chat-completion refine; needs

`OPENAI_API_KEY` + `OPENAI_BASE_URL`; best-effort; never authors patches.

## Candidate refs feed the targeted build

A discovered candidate reference now drives the enablement targeted build

(compiled-component acquisition), not just the git-apply/bench path:

- A candidate is resolved to a checkoutable ref — a PR reference becomes that

PR's head ref — so support that only exists in an unreleased PR/branch is

reachable, not just released-tag autoselect.

- The source PR URL is recorded as build provenance and surfaces in the session

breakdown's `build_attempts[].installed_versions` as `source_pr_url`.

## Enablement ladder (methodology)

When a candidate is for enablement (making a `(model, backend)` combo that is

non-runnable, or boots but fails its accuracy eval, run correctly — not perf),

the repair follows a tiered ladder — diagnose the

missing capability layer once, then climb only as far as needed: Rung 0

diagnose, 1 serve-flag/config wire-up, 2 in-tree source patch, 3 attempt-scoped

runtime, 4 source localization, 5 off-loop compiled build. A supported-but-un-wired

model needs only the cheap top rungs; a genuinely-new architecture climbs higher.

The canonical rendered text is `build_enablement_ladder_book` in

`hyperloom.agents.framework.enablement_ops` (injected into the enablement

authoring specialist's prompt); see also `docs/conceptual/optimization-loop.md`

("Enablement escalation ladder").

## KB partition (`fa kb`)

Read priors before generating a patch; write lessons only after a KEEP

verdict. Operations all live under the `framework_optimization` domain:

```bash

fa kb list # list available KB domains

fa kb show --domain framework_optimization # show files in a domain

fa kb search --query "chunked prefill" # case-insensitive content search

fa kb contribute --domain framework_optimization --body-file finding.md

fa kb synthesize --domain framework_optimization --findings findings.json [--with-llm]

```

`contribute` appends to `${KB}/<domain>/empirical_kb.md`, creating the domain

dir and file if missing. The `framework_optimization` partition already exists

in a fresh install — it ships `cross_framework_map.jsonl` (package data) as its

only seed.