Files
canina/infra/hermes-pilot/README.md
T

79 lines
7.7 KiB
Markdown

# Real bounded Tech/Dev Hermes pilot (experimental, NOT enabled)
Owned files only in `infra/hermes-pilot`; no existing core, module, tracer, profile or runtime config changed. No push/deploy/RELEASE_AUTHORIZE. Do not wire this into the existing tracer completion endpoint: that endpoint deliberately accepts only deterministic JSON.
## Fixed task and boundaries
Task `tech-dev-clamp-quantity-v1`: produce one <=2048-byte Python `clamp_quantity(quantity)` implementation, integer range 0..99. No input/browser prompt is accepted. The model has **zero tools**, no shell/browser/Git/deploy credentials. Trusted code alone writes `quantity.py`, runs separate AST-allowlisted QA (9 boundary cases), and commits an isolated, remote-free fixture repository. This is real generated-code QA, not application QA. Source commit is recorded as provenance, not represented as the fixture's base commit.
`infer.py` uses installed `run_agent.AIAgent`, verified from the installed signature and `agent/agent_init.py`; `enabled_toolsets=[]` is additionally enforced by asserting empty `agent.tools`. Existing approved `OPENAI_API_KEY` is read in memory only; no messaging/API-server credentials/auth pools copied. Separate temporary HERMES_HOME, no memories/context/background review/fallback. Provider/model pinned to current canina-hermes `custom`, `https://nr.parsaaghayi.ir/v1`, `Free`; no provider installation or account changes. Existing configs remain untouched. Model output is untrusted and never directly shell-executed; QA rejects all syntax except the single nested min/max return expression before isolated Python execution.
Installed image identity: `sha256:373ddd5e6649f525b17993e1c885cdf1352127f8e98fd329140a73237125e52f`, install stamp commit `818c13be1dc4fd28987e1e881a9408224afd4535`, v0.21.6. Discovery: `/opt/hermes/hermes chat --help` supports `--oneshot`, `--max-turns`, `--run-budget`; `/opt/hermes/.venv/bin/python` loads installed API. Official skills and https://hermes-agent.nousresearch.com/docs/llms.txt consulted. The initially guessed developer API docs URL returned404; installed source/signature is authoritative for this pinned build.
## PREPARE mapping — parent integration required
`executor.execute(lease, artifact_root, infer, heartbeat)` only accepts a fresh staging, first-attempt, 20-cent, 40hex-source lease and exact lease fields; heartbeat failure aborts before inference and before QA/commit. Trusted adapter must obtain this lease via existing authenticated claim AFTER independent Gate1/READY, verify the explicitly allowlisted task identity/scope/criteria server-side, and supply heartbeat connected to the authenticated backend. A caller-created dict is NOT an authorization. Never expose this Python interface to browser requests.
## Heartbeat runner and parent API (this revision)
After independent READY/Gate1, allowlist and provider-cap admission, parent constructs
`runner = executor.pinned_inference(executor.IMAGE)` and calls
`executor.execute(authenticated_lease, artifact_root, runner, authenticated_heartbeat)`.
Only trusted Python may construct runners. Callback receives an unchanged COPY of the
original lease binding (taskId/runId/leaseToken), must use authenticated server transport,
and must raise on any non-2xx, ownership/fencing/expiry denial or malformed response.
Explicit `False` also denies; `None` means success for existing raise-on-error adapters.
Callback MUST impose <=5s network timeout, no retries; a blocked callback thread cannot
be forcibly killed by Python. It is daemonized; its result cannot restart inference or
extend a local lease. Parent must serialize executions per server lease; the runner is
single-use and concurrent reuse of that runner is locked out. This is not a browser API.
Immediate initial heartbeat; dedicated ongoing thread waits 5s between acknowledged
calls. With required <=5s transport ceiling, heartbeat starts are <=10s apart. A stalled
heartbeat (10s without acknowledgment), exception or denial aborts actual subprocess
inference, not just its caller. No leaseUntil mutation/local extension occurs. Fresh
server-authorized heartbeats retain fencing; this code cannot create authorization.
Guard checks also fence QA/artifact commit/report return. A denial during QA prevents
report return; any partial local fixture is not accepted completion evidence.
Monotonic wall ceiling 90s with cancellation reserve: work aborts at85s, remote kill
command <=2s and local reap <=1s; bounded QA3s/Git1s. Pinned runner uses one model
call, max_iterations1/max_tokens160, run_budget80s, tools0, no retries. An independent
in-container timeout85s survives loss of the Docker client. Cancellation addresses
the actual in-container process session via a random PID file plus cancellation
marker (handles cancellation before PID publication); it kills that process group.
Cancellation transport failure raises and prevents success, but cannot prove immediate
remote death; independent inner timeout is the fallback. Small random marker files
in container /tmp are intentional fencing tombstones, not configuration changes.
`rehearse.py` remains synthetic, never a live lease. It uses this cancellable runner
but is NOT admission evidence. Do not run it until provider-cap approval. Existing
20-cent reservation remains UNKNOWN, never zero, and no completion/claim/release or
backend transport is implemented here. Existing tracer endpoint still rejects model
reports; parent must separately implement authenticated allowlisted artifact ingestion.
No changes to installed Hermes or runtime/profile configuration.
## Actual evidence and blockers
Evidence directory `/opt/services/canina/validation/v4-real-pilot`:
- `red.log`: missing executor assertion failed before implementation.
- `inference-private.log`: actual installed Hermes/provider inference exit0 under75s diagnostic ceiling; generated source saved, not fabricated. This ceiling was ONLY diagnostic, not accepted as a PREPARE lease run.
- `model-artifact/quantity.py`: actual model artifact; independent QA passes9 cases, SHA256 `0125246b551896c5f9ee98fabeb02982a6690a9974c0eb24ef3ae676d46380d5`; isolated Git commit `95cb3d27d636ae817d6a778e8053e2f87b50e57b`.
- `actual.log`: bounded full rehearsal failed with inner timeout exit137 at18s; no completion/QA success was assumed. Previous client-only timeout was corrected to inner process kill. **Installed model/startup cannot currently complete reliably inside30s PREPARE lease without authenticated ongoing heartbeat.** Do not extend lease locally or call the75s diagnostic a bounded lease success.
Contract tests: `python3 infra/hermes-pilot/test_contract.py`. Parent still owns backend integration, authenticated heartbeat orchestration, allowlist admission, billing caps, signed artifact transport and Stage CI. This commit is a real generation/independent-QA proof and fail-closed executor seam, not a live autonomous Tech department or released product.
## Verification of heartbeat revision
`python3 -m unittest discover -s infra/hermes-pilot -v`: 11 passing tests, including
real OS child/descendant cancellation, ongoing rejection, stalled heartbeat, wall
ceiling, concurrent runner reuse, immutable lease and unknown-cost preservation.
The artifact success test is explicitly a deterministic process fixture, NOT model
inference. TDD red observed for missing ongoing runner and explicit false denial;
additional cancellation/concurrency regression cases were added and executed.
Previously generated real model artifact was rechecked by current AST allowlist QA:
9 cases pass, SHA256 `0125246b551896c5f9ee98fabeb02982a6690a9974c0eb24ef3ae676d46380d5`.
No new real inference was run: README provider pricing/cap gate remains unresolved.
Docker cancellation path is implemented but not runtime-exercised here; OS process
group cancellation is exercised. No live backend/claim/release, push or deploy.