Skip to content

Latest commit

 

History

History
164 lines (158 loc) · 18.3 KB

reference.md

File metadata and controls

164 lines (158 loc) · 18.3 KB

hookprobe — reference

Generated from the code: environment names and defaults from settings.py, routes and their first sentence from the handlers. Correct it by editing the comment beside the field or the handler's docstring — an edit here is lost on the next run, and scripts/gen_reference.py --check will say so.

Environment (81)

variable default what it is
HOOKPROBE_ESCALATE_LEVELS critical,high Severities that may wake a person, as a comma-separated list
HOOKPROBE_MCP_CONFIG (empty) MCP server config handed to the engine; empty means none
HOOKPROBE_TOKEN (empty) Inbound: callers authenticate with a single bearer token (an OpenClaw-dialect client presents its hooks token here)
HOOKPROBE_MODEL claude-opus-5 Engine: which Claude model runs the investigation and how hard the runtime caps it
HOOKPROBE_CODEX_CONFIG (empty) The Codex provider config copied into the home this node owns
HOOKPROBE_PI_CONFIG (empty) The operator's pi configuration directory, read and never written
HOOKPROBE_SYSTEM_PROMPT_APPEND (empty) Operator methodology appended to the engine's own system prompt, read fresh at every run (hot-editable)
HOOKPROBE_AGENTS_CONFIG (empty) Named subagent roles (JSON: name -> {description, prompt, tools?, model?, skills?}), the config-file twin of .claude/agents/*.md files
HOOKPROBE_REMEDIATION_ALLOWLIST (empty) Remediation executor gate: a file of full-match regexes, one per line, hot-read at execution time
HOOKPROBE_BLAST_RADIUS (empty) The blast radius a WRITING node declares about itself: one measured line per entry, exactly as /v1/posture reports it
HOOKPROBE_REMEDIATION_HIGH_RISK_ALLOWLIST (empty) The second gate, for steps the report itself called high risk: a high step must full-match a pattern in BOTH files
HOOKPROBE_EVENT_SECRET (empty) The hookstack loop
HOOKPROBE_ACTION_SECRET (empty) The card-action door's own secret
HOOKPROBE_PRICE_IN_PER_1M 0.0 What a token costs on THIS gateway, per million, as the operator states it
HOOKPROBE_PRICE_CACHE_READ_PER_1M 0.0 Tokens read back from the prompt cache — a tenth of fresh input here, so pricing them as input over-states a cached turn tenfold
HOOKPROBE_PRICE_CACHE_WRITE_PER_1M _float('HOOKPROBE_PRICE_IN_PER_1M', 0.0) Tokens written INTO the cache
HOOKPROBE_PRICE_OUT_PER_1M 0.0 Output tokens, dollars per million
HOOKPROBE_RETURN_SECRET (empty) Outbound HMAC secret; signs the finding on its way back
HOOKPROBE_RULING_URL (empty) Where a retrospective condition ruling goes, and the credential for that ONE door
HOOKPROBE_RULING_SECRET (empty) Signs the rulings this service posts to the judge
HOOKPROBE_MEMORY_AUTO_APPLY True Apply a suggested environment fact without waiting for a person, when its SHAPE cannot act (hookprobe.suggestions._UNSAFE)
HOOKPROBE_DECLINE_PATTERNS (empty) Path to a file of full-match regexes over alert TITLES this node declines at its event door — the families it has no instrument for; unset = decline nothing
HOOKPROBE_BUDGET_GATES_AGENT_DOOR False Whether the breaker above also refuses NEW sessions on /hooks/agent
HOOKPROBE_ALARM_MIN_INTERVAL_SECONDS 600 Floor between two alarm sends, so a storm cannot page repeatedly
HOOKPROBE_HOST 0.0.0.0 Address the service binds to
HOOKPROBE_PORT 8088 Port the service listens on
HOOKPROBE_AGENT_TOKEN (empty) The bearer the AGENT holds, which is deliberately not the one above
ANTHROPIC_BASE_URL (empty) WHERE that model name is sent
HOOKPROBE_MAX_TURNS 32 Ceiling on engine turns in one investigation
HOOKPROBE_MAX_CONCURRENT 2 How many investigations may run at once
HOOKPROBE_DEFAULT_TIMEOUT_SECONDS 900 Wall-clock budget for an investigation that does not ask for one
HOOKPROBE_MAX_TIMEOUT_SECONDS 1800 Ceiling on what a caller may ask for
HOOKPROBE_WORKDIR /data Workspace: one persistent volume
HOOKPROBE_REPEAT_REMINDER_AT 3 Loop hygiene (hygiene.py), all advisory — the security boundary stays the bash guard plus read-only credentials
HOOKPROBE_HANDOFF_SECRET (empty) Signs that one delivery, timestamped, exactly like every other hop here
HOOKPROBE_BASH_TIMEOUT_MS 120000 Default timeout for one shell command the engine runs
HOOKPROBE_BASH_MAX_TIMEOUT_MS 600000 Ceiling on what a single command may ask for
HOOKPROBE_AUTO_DISTILL_MAX 0 Auto-distill: how many runbooks a finished run may leave behind for the next one, written by the service (never by the agent — see hookprobe.inputs)
HOOKPROBE_RULING_TTL_DAYS 14 How long a standing not_worth_it ruling may keep answering a condition from its runbook instead of starting a paid engine run
HOOKPROBE_RULING_REVERIFY_DAYS 7 A ruled-useless condition still gets a REAL investigation this often — the evidence behind a ruling goes stale, and a gate that never re-checks would keep citing last month's case…
HOOKPROBE_RUNBOOK_ANSWER_DAYS 0 How long a condition whose last REAL investigation a person ruled USEFUL may answer a re-fire from that runbook instead of paying for a cold-start, 0 = off (the default)
HOOKPROBE_REFIRE_ANSWER_HOURS 0 Hours after a REAL investigation of a condition during which a re-fire at the same level, with no recovery recorded between, is answered from that investigation's report at $0 inst…
HOOKPROBE_COALESCE_WINDOW_SECONDS 1800 Storm coalescing at the event door: a re-fire of the same alert (same source + title, new event id) within this many seconds continues the existing investigation instead of funding…
HOOKPROBE_CONSOLIDATE_AT 5 Consolidation: at this many accumulated cases, a runbook triggers one agent run that drafts a curated procedure from the case pile
HOOKPROBE_REMEDIATION_COOLDOWN_SECONDS _cooldown_default() Remediation cooldown: seconds a target is left alone after a procedure has acted on it
HOOKPROBE_REMEDIATION_VERIFY_SECONDS _verify_default() How long an executed procedure waits for the condition to answer before the board calls it held: a recovery inside the window (or after it) holds it, a re-fire inside it says it di…
HOOKPROBE_AUTOMATION_TIERS (empty) The declared ceiling per class of automation — see automation.py
HOOKPROBE_BUDGET_USD 0.0 The budget breaker, guarding the only path that spends money without a human asking: once the window's recorded spend reaches budget_usd, the event door refuses NEW investigations…
HOOKPROBE_BUDGET_WINDOW_HOURS 24.0 Window the spend ceiling is measured over
HOOKPROBE_RETENTION_DAYS 0 Volume retention (days): case files and engine transcripts older than this are pruned daily
HOOKPROBE_SCRATCH_DAYS 7 Scratch retention (days): the agent subprocess's TMPDIR ({workdir}/scratch) and the CLI's own transport logs under $HOME/.cache are pruned daily when older than this, whatever rete…
HOOKPROBE_SELFTEST_EVERY_SECONDS 3600 How often the node demonstrates its own boundaries (/v1/selftest) and tells the alarm channel when one does not hold
HOOKPROBE_PI_PROVIDER (empty) Which provider in that configuration serves this node's model
HOOKPROBE_SKILLS (empty) Directory of skills the engine may load
HOOKPROBE_RETURN_URL (empty) The one door findings go back to
HOOKPROBE_ALARM_URL (empty) Direct self-alarm, around the pipe: report returns that exhaust their retries, a run failing in a way every run here would, the hourly selftest, and a transient failure that recurs…
HOOKPROBE_SETTING_SOURCES project Skill layers
HOOKPROBE_CODEX_BINARY (empty) Codex only
HOOKPROBE_CODEX_PYTHON (empty) The interpreter the Codex adapter spawns its tool gate with
HOOKPROBE_PI_BINARY (empty) pi only
HOOKPROBE_PI_PYTHON (empty) The interpreter the pi gate extension spawns
HOOKPROBE_HANDOFF_URL (empty) Where a finished run's report goes when an operator clicks "hand off", and the credential for that one door
HOOKPROBE_AGENT_ROLE (empty) One line saying what this agent is FOR, shown wherever its work is listed
HOOKPROBE_RELAY_UI_URL (empty) Where the pipe's board is, as a BROWSER reaches it (not as this container does): a run then links to the chain it belongs to
HOOKPROBE_PUBLIC_URL (empty) Where this node can be reached from OUTSIDE, if anywhere
HOOKPROBE_AGENT_NAME (empty) Who this node is
HOOKPROBE_MCP_TOOLS (empty) Which MCP tools this instance may actually call, as a closed set — mcp__chat__chat_search_messages or mcp__chat__* for a whole server
HOOKPROBE_FOLLOW_UP_SENDERS (empty) Who may continue an investigation by replying in its chat thread (events.py, kind: follow_up): platform sender ids, * for anyone the bridge forwards, empty for nobody — the default…
HOOKPROBE_RESUME_INTERRUPTED on Whether a run this process finds mid-flight at startup — left by a crash, an OOM kill or a redeploy — is CONTINUED in its own engine session or settled as a failure
HOOKPROBE_VERDICTS (empty) The closed vocabulary this instance is allowed to CONCLUDE with, so a report can steer the next hop instead of only being read
HOOKPROBE_RUNTIME (empty) WHICH runtime runs a turn
HOOKPROBE_BASH_GUARD (empty) Which posture the bash guard takes
HOOKPROBE_POSTURE_CHECK (empty) Whether the credentials are checked against that declaration at startup (posture.py): enforce refuses to start a runner declared readonly whose kubeconfig or AWS identity can mutat…
HOOKPROBE_TELEMETRY_RECEIVER (empty) Whether this service receives its own runs' OpenTelemetry (telemetry.py): on points the CLI at POST /otel/v1/{logs,metrics} here, keeps a per-run timing record under {workdir}/tele…
HOOKPROBE_SYNTHETIC_KEY_PREFIXES (empty) Session-key prefixes that mark a run SYNTHETIC — a drill, a by-hand check, a wiring test — so it is kept out of the books: no runbook is distilled from it, it anchors no re-fire an…
HOOKPROBE_SESSION_KEY (empty) Which run this tool call belongs to, so the flight recorder can say
HOOKPROBE_GATE_AUDIT (empty) Where the flight recorder writes
HOOKPROBE_GATE_MODE READONLY The posture this call is judged against, passed by the adapter from bash_guard
HOOKPROBE_GATE_WORKDIR (empty) The run's own volume, so the input guard knows which files steer the next run and may not be written by this one
HOOKPROBE_GATE_HOME (empty) The agent's home, whose settings and skills are inputs too
HOOKPROBE_GATE_MCP (empty) The MCP tools this node may call, from mcp_tools

Routes (65)

method path what it does
GET / Redirects to the board
GET /healthz Liveness only — the engine is not consulted, so a stuck run cannot hide a live process
POST /hooks/action A card press forwarded by the pipe: accept a memory line, rule a run useful or useless — signed, idempotent, and answered with what changed
POST /hooks/agent Start an investigation from a finished prompt (idempotent per sessionKey)
POST /hooks/event The pipe's door: a signed alert either starts a paid investigation, coalesces into one already running, or is declined by level, budget or a standing ruling — every decline says wh…
GET /metrics Prometheus text format, rendered by hand — three gauges are not a client-library dependency
POST /otel/v1/{signal} OTLP/http-json receiver for the CLI this service launches — and nothing else: the per-process header is the credential, the run's session-key attribute is the address, and a body f…
POST /sessions/{session_key}/continue Follow-up turn in a finished investigation; poll /final for the answer
GET /sessions/{session_key}/final Poll for the finished report: 202 while running, then the full text once
POST /sessions/{session_key}/stop Cancel the in-flight turn; it settles as a failed turn within a poll
GET /static/manifest.webmanifest The web manifest, named for this node; start URL and scope are relative, so a prefix keeps them
GET /sw.js The console's service worker: the page and the icons offline, never the data (static/sw.js)
GET /ui The operator board
GET /v1/agent What this node IS: identity, runtime, the policy it runs under, health
GET /v1/agent/description The same node in ANP's dialect: what it can be asked, and what stops for a person
GET /v1/agents The subagent roles the engine is offered
DELETE /v1/agents/{name} Remove a role; the engine stops being offered it on the next run
GET /v1/agents/{name} One role's definition, whole
PUT /v1/agents/{name} Create or replace a role definition, size-checked and atomic
GET /v1/audit The flight recorder, newest FIRST
GET /v1/automation Each class of automation, its declared ceiling, its record, and whether the two agree — plus the tier the record WOULD support
POST /v1/automation/{cls}/{item_id}/regret A sampling review, after the fact, saying an auto-applied action was wrong
GET /v1/budget The breaker's arithmetic: window spend, ceiling, cache ratio and the worth line
GET /v1/config The operational knobs, redacted: secret VALUES never appear — booleans say whether they are set
GET /v1/declines What the decline list did inside a window: events declined at the door, distinct conditions, per pattern
GET /v1/live The session list's wake-up line, the same shape the other two boards use
GET /v1/mcp What the next run would load — read fresh from the config file
GET /v1/memory CLAUDE.md as the engine will read it, plus its path
PUT /v1/memory Replace CLAUDE.md whole, size-checked and atomic — the memory page's save button
GET /v1/memory/suggestions Facts investigations proposed for the environment memory
POST /v1/memory/suggestions/{suggestion_id}/accept Adopt one queued line into CLAUDE.md under its own heading
POST /v1/memory/suggestions/{suggestion_id}/dismiss Drop one queued line; nothing is written to memory
GET /v1/posture What the credentials could do when this runner started, measured against the declared posture — the record behind "this ran read-only"
GET /v1/remediations Open remediation proposals, newest first, each saying whether it is still runnable
POST /v1/remediations/{proposal_id}/approve The one click that makes anything run
POST /v1/remediations/{proposal_id}/reject Refuse a parked proposal; it keeps its file, marked rejected
POST /v1/rulings A person rules on a CONDITION — is this alert worth investigating again
GET /v1/runs Finished runs, newest first
POST /v1/runs/rulings File verdicts on several investigations at once — was this RUN worth it
GET /v1/runs/{session_key} One run whole: turns, meta, ruling, cost
GET /v1/runs/{session_key}/audit The accountability record of one run: what posture it held, what it cost, every tool call it made and every one the guards refused, and whether its steering inputs changed under it
POST /v1/runs/{session_key}/distill A skill draft for what this run learned — returned, never saved
POST /v1/runs/{session_key}/handoff Hand this run's report to the pipe, for whichever node the operator wired that door to
GET /v1/runs/{session_key}/patch The diff a work run left behind, as text/plain — reviewable, quotable, git apply-able
POST /v1/runs/{session_key}/retry Human takeover: try a failed investigation again from the board
POST /v1/runs/{session_key}/ruling One run, ruled from the sessions page — and told what the ruling DID
GET /v1/runs/{session_key}/stream The open session's steps, pushed as they happen (NDJSON, one per line)
GET /v1/runs/{session_key}/telemetry The shape of one run: every model call and tool call on one time axis, with what each cost, from the telemetry the CLI posted to this service
GET /v1/selftest Every boundary this node claims, demonstrated right now
GET /v1/skills Every runbook with its review state and case count, newest first
GET /v1/skills/export Runbooks packaged to LEAVE this deployment — see hookprobe.export
DELETE /v1/skills/{name} Only the project layer is deletable
GET /v1/skills/{name} One runbook's manifest, whole
PUT /v1/skills/{name} Writes always land in the project layer: editing a read-only user-layer skill saves a project copy that shadows it from then on
GET /v1/skills/{name}/history Every version a write displaced, newest first — the undo the review page stands on
GET /v1/skills/{name}/history/{stamp} One archived version of a runbook, as it was
POST /v1/skills/{name}/history/{stamp}/restore Put a displaced version back, in one call
GET /v1/skills/{name}/origin The full provenance record — every revision, not just the last one
GET /v1/skills/{name}/proposal The consolidation draft awaiting review, beside the manifest it would replace
POST /v1/skills/{name}/proposal/approve The consolidation becomes the manifest — through the same door every write uses: the displaced version is snapshotted first, and approving IS the review, so the runbook flips to re…
POST /v1/skills/{name}/proposal/reject Drop the draft, note that somebody did — the manifest is untouched and the threshold will re-arm as cases keep arriving
POST /v1/skills/{name}/review Mark a runbook read without changing a character of it
GET /v1/system-prompt The appended methodology file as the engine will read it
PUT /v1/system-prompt Replace the appended methodology, size-checked and atomic — read fresh at the next run
GET /v1/work The board: one row per piece of work, not per run