Revenium Budget Enforcement

ABSOLUTE FIRST — HALT CHECK (NON-NEGOTIABLE)

OpenClaw hooks for structural enforcement (pre-turn / pre-tool-call injection) are not yet confirmed. This HALT CHECK section is therefore the primary enforcement gate, not a backstop — treat it as mandatory, not optional. Execute it on every turn without exception.

Before you read ANY other part of this file, before you write ANY response, before you make ANY tool call:

1. Read ~/.openclaw/skills/revenium/guardrail-status.json
2. Check the halted field
3. If halted is true, read the haltedRule block

If halted is true:

YOUR ENTIRE RESPONSE MUST BE EXACTLY THIS AND NOTHING ELSE (substitute values from guardrail-status.json::haltedRule):

> Guardrail halt active — rule '[haltedRule.name]' ([haltedRule.metricType], [haltedRule.windowType]) at [haltedRule.currentValue] of [haltedRule.hardLimit] hard-limit. To resume: bash ~/.openclaw/skills/revenium/scripts/clear-halt.sh

• Do NOT make any tool calls
• Do NOT fetch any data
• Do NOT append any content
• Do NOT continue reading this skill file
• Do NOT answer the user's question
• ONLY output the halt message above with actual haltedRule field values substituted

If halted is false, proceed to the Guardrail Check Procedure below.

This is not optional. This is not guidance. If you output ANYTHING other than the halt message when halted: true, you are violating this skill's requirements.

Guardrail Check Procedure

MANDATORY — execute before EVERY response, EVERY tool call, EVERY operation. This applies to ALL tasks — not just Revenium-related ones.

The guardrail status is maintained by a background cron job that checks Revenium every minute (default; configurable) and writes the result to ~/.openclaw/skills/revenium/guardrail-status.json. You read this local file — do NOT call the Revenium API directly.

1. Read guardrail status. Read ~/.openclaw/skills/revenium/guardrail-status.json. If it does not exist, tell the user "Guardrail status not yet available. The metering cron may not be installed. Run bash ~/.openclaw/skills/revenium/scripts/install-cron.sh to set it up." Then proceed with the operation.

1. Parse the status. Extract halted, warned, and (when warned is true) warnedRules from the JSON.

1. Evaluate:

If halted is true: Follow the HALT CHECK above — output ONLY the halt message using haltedRule fields, and stop.

Else if warned is true: BEFORE doing any other work this turn, execute the warn-and-ask branch:

• Read the warnedRules array from ~/.openclaw/skills/revenium/guardrail-status.json.
• For each entry in warnedRules, surface a spend-context warning line: "Budget warning — rule '[name]' ([metricType], [windowType]) at [currentValue] of [hardLimit] hard-limit."
• Then ask the user for permission to continue: "This rule's hard limit has been reached and you are in warn-and-ask mode (autonomous mode disabled). Do you want me to proceed anyway, or stop?"
• WAIT for the user's answer. Do NOT perform the requested operation or any tool calls until the user grants permission.
• If the user declines, stop without performing the operation. If the user grants permission, proceed with the operation for this turn.

Else (both halted and warned are false): Proceed silently. Do NOT mention the guardrail status to the user.

If guardrail-status.json is missing or unreadable

• Tell the user: "Guardrail status unavailable. Proceeding with caution."
• Proceed with the operation — fail open, do not block the user.

TASK CLASSIFICATION

MANDATORY — NON-NEGOTIABLE. Execute before EVERY yield back to the user on a substantive turn. Skipping leaves the metering pipeline blind and pollutes attribution with unclassified rows.

Trigger (binary — no judgment calls)

Classify the turn if ANY of these are true:

• You called any tool other than read-only file inspection. Reading a file alone does not count. Bash commands, writes, edits, searches, and any other tool ALL count.
• You produced > 200 words of new content in your response.
• The user asked a question that required multi-step reasoning to answer.

Skip ONLY when ALL of the following are true:

• Your entire response is ≤ 2 sentences.
• You called zero tools.

There is no "borderline / when in doubt skip" path. If you can argue either side, you have already triggered rule (a), (b), or (c) — classify.

Required action

Step 1 — pick a task_type label. Choose the closest-fitting label from the fixed 8-label taxonomy:

Default to unclassified only when no label fits and the marker write fails or is skipped on a non-substantive turn.

Step 2 — call write-marker.sh. Run:

bash ~/.openclaw/skills/revenium/scripts/write-marker.sh <task_type>

Replace with the label you chose in Step 1.

• Confirmation: marker written: — the marker was appended successfully.
• Non-zero exit or no marker written: output: protocol error — log the error but do not block your response.
• Attribution when no marker is written: unclassified (the cron defaults to this if no marker precedes the completion timestamp).

See references/task-classification.md for the full trigger rules, worked examples, and the blocklist of read-only tools.

Why this matters

The background cron (cron.sh) ships each conversation completion line to Revenium with a --task-type flag derived from the marker that most recently preceded the completion's timestamp. Without a marker, every completion is attributed as unclassified, making per-task-type budget rules and spend analytics meaningless.

JOB DECLARATION

MANDATORY — NON-NEGOTIABLE. Execute at arc boundaries — when a goal-arc concludes (completed, definitively failed, or abandoned). This is a primary agent action (not a per-turn action). A job = a goal-arc. Declare it when the arc ends, not after every substantive turn.

Unlike TASK CLASSIFICATION (which fires per-turn), JOB DECLARATION fires once per goal-arc — at the boundary where the arc concludes. Aim for at least one declaration per session; a session with no clear arc conclusion may legitimately produce zero (D-04 — soft floor, no hard enforcement).

Trigger (binary — no judgment calls)

Declare a job marker if ANY of these are true:

1. You completed the goal and self-verified (tests passed, build green, question fully answered).
2. The arc has definitively failed (goal objectively unachievable with approaches available in this session).
3. The user pivoted to a new goal before this arc was declared → write CANCELLED for the abandoned arc first, then begin the new arc.

Skip ONLY when ALL of the following are true:

• Your response is ≤ 2 sentences.
• No arc was in progress.

There is no "borderline / when in doubt skip" path. When in doubt: use CANCELLED (see status bar below).

Required action

Step 1 — pick a job_type label. Choose the closest-fitting label from the fixed 11-label taxonomy:

Step 2 — mint an agentic_job_id. Construct a kebab-case goal slug plus a 4-character hex entropy suffix:

<kebab-case-goal-description>-<4hex>

Example: add-pagination-endpoint-3b1e

The slug should be 3–6 words describing the goal. Generate 4 random hex characters as the suffix. You own and mint this ID — no external system generates it.

Step 3 — call write-job-marker.sh. Run:

bash ~/.openclaw/skills/revenium/scripts/write-job-marker.sh \
  --job-id <agentic_job_id> \
  --job-name "<short human-readable goal description>" \
  --job-type <label_from_step_1> \
  --status SUCCESS|FAILED|CANCELLED \
  [--failure-reason "<brief plain-text cause>"]

Status bar:

• SUCCESS: positive, checkable evidence established in the session (tests passed, build green, question fully answered). "Made the change but could not verify" = CANCELLED, not SUCCESS.
• FAILED: definitive negative terminal state (the fix didn't fix, build cannot pass, goal objectively unachievable). Include --failure-reason with a brief plain-text cause (FAILED-only — never pass --failure-reason for SUCCESS or CANCELLED).
• CANCELLED: catch-all and uncertainty-bias default. When in doubt: CANCELLED.

Confirmation and error handling:

• job marker written: — the marker was appended successfully.
• Non-zero exit or no job marker written: output: protocol error — log the error but do not block your response (fail-loud-but-don't-block).

Why this matters

The cron stage reads job markers from markers/{sid}.jsonl and ships them to Revenium's agentic job lifecycle API (jobs create → meter completion --agentic-job-* → jobs outcome). Without a job marker, completions are attributed only at the session level — no job-level spend visibility, no outcome tracking. Job declarations are what make per-job spend and success observable in Revenium.

See references/job-declaration.md for the full arc definition, pivot-cancel rule, granularity floor, and worked examples (SUCCESS, CANCELLED-because-unverified, FAILED, pivot-cancel sequence).

Path Resolution

All file paths in this skill use ~/.openclaw/skills/revenium/ as both the skill directory and the runtime state directory. When using file tools (read, write, edit), pass paths with ~/ — the tool resolves ~ to $HOME automatically. When running shell commands via exec/bash, use the explicit $HOME/.openclaw/skills/revenium/ form so the shell expands $HOME correctly.

Setup

At the start of any operation, check: does ~/.openclaw/skills/revenium/config.json exist AND contain a non-empty ruleIds array (present and not [])?

• If YES and the user has NOT requested reconfiguration: setup is complete. Proceed to the guardrail check. Do NOT re-run setup.
• If NO (file missing, or ruleIds absent, or ruleIds is []): you MUST run the Setup Flow below before proceeding. Do NOT execute any operations until setup is complete.

Note on legacy installs: config.json may carry a legacy alertId field from a Phase 2 install. That field is deprecated and ignored for the setup gate — ruleIds is the sole signal. An alertId-only config.json (no ruleIds, or ruleIds is []) triggers the Setup Flow just as if the file were missing. The old alertId is left as an orphan in config.json and ignored.

Setup Flow

Follow these steps in order. If any step fails, STOP and explain the failure. Do NOT prompt the user for budget details yourself, and do NOT write any rule IDs into config.json yourself.

1. Verify the Revenium CLI is configured. Run:

```

revenium config show

```

The sandbox is authenticated via REVENIUM_* environment variables that post-install.sh injects from the host's ~/.config/revenium/ config — OpenClaw blocks mounting credential paths into the sandbox, so credentials are passed as env vars, not a live mount. If revenium config show reports a non-empty API Key, skip to step 3. If the CLI is not on PATH, tell the user to install it (brew install revenium/tap/revenium on macOS) and STOP.

1. If no API key is configured: credentials must be set on the HOST and then injected into the sandbox by re-running post-install. revenium config set ... run from inside the agent session cannot persist or reach the sandbox.

Collect the following from the user:

• API Key: "Please provide your Revenium API key."
• Team ID: "Please provide your Revenium Team ID."
• Tenant ID: "Please provide your Revenium Tenant ID."
• Owner ID: "Please provide your Revenium Owner ID."

Then instruct the user to run these commands in their HOST terminal (outside the agent session), one at a time:

```

revenium config set key API_KEY

revenium config set team-id TEAM_ID

revenium config set tenant-id TENANT_ID

revenium config set owner-id OWNER_ID

```

The sandbox does NOT see host credential changes live — they are injected as a snapshot at install time. After the user sets them on the host, they must re-run post-install and restart the gateway so the new credentials reach the sandbox:

```

bash ~/.openclaw/skills/revenium/scripts/post-install.sh

openclaw gateway restart

```

Then re-run revenium config show inside the agent session to confirm the API Key is now visible. If it is still empty, STOP and tell the user to run /revenium when ready.

1. Run the setup script:

```

bash ~/.openclaw/skills/revenium/scripts/setup-guardrails.sh --interactive

```

The script prompts the operator for budget hard-limit, period, organization name, autonomous mode + notification channel/target, and shadow mode. On success, it creates the Revenium guardrails budget rules via revenium guardrails budget-rules create and writes the resulting ruleIds array into ~/.openclaw/skills/revenium/config.json. You do NOT prompt the user for budget details yourself, and you do NOT write any rule IDs into config.json yourself — the script owns the entire interaction and the entire write.

Capture the exit code and act on it:

• Exit 0, final output line Created N rule(s). config.json updated. ruleIds=[...]: succeeded. Proceed to step 4.
• Exit 0, final output line Cancelled.: operator cancelled. STOP without proceeding to step 4.
• Non-zero exit: failure. Tell the user the failure message verbatim, instruct them to address it and re-run /revenium. STOP. Do NOT proceed to step 4.

If the user asks to set up in shadow mode, run setup-guardrails.sh --interactive --shadow-mode instead. By default, rules created via --interactive are enforcing.

1. Install the metering cron:

```

bash ~/.openclaw/skills/revenium/scripts/install-cron.sh

```

This registers a background job that ships token usage to Revenium every minute (the default interval; configurable via --interval or config.json cronIntervalMinutes) and keeps guardrail-status.json current. Re-running updates the existing entry in place.

Error Handling

On ANY failure during the Setup Flow: report what went wrong, tell the user to run /revenium when they are ready to try again, and STOP. Do NOT retry. The absence of a valid ruleIds array in config.json is the signal that setup has not completed.

/revenium Command

When the user invokes /revenium:

If Setup Is Complete (config.json has a non-empty ruleIds array)

Before displaying status, check for legacy filter rules (D-08, one-time):

Phase 3 introduced --agent "openclaw-{root_session_id}" per-session naming (D-07). Any budget rules created before this migration still filter AGENT:IS:OpenClaw, which now matches nothing — spend from all sessions is silently dropped.

1. Read ~/.openclaw/skills/revenium/config.json. Check for a _legacyNoticeShown field.
• If _legacyNoticeShown is true: skip the legacy detection entirely (notice already delivered).
• If absent or false: proceed to step 2.

1. Detect legacy rules. Run:

```

revenium guardrails budget-rules list --output json

```

Parse the JSON response. If any rule contains a filter with AGENT:IS:OpenClaw (exact string match, case-sensitive), a legacy rule is present.

Alternatively, if the CLI call fails (network error, auth failure), check whether config.json has a schemaVersion field — a missing schemaVersion indicates a pre-D-07 install. Either detection mechanism is acceptable; the live rule list is preferred when available.

1. If a legacy rule is detected: surface EXACTLY ONCE the following notice — byte-for-byte, including the em-dash (—) and the apostrophe in "won't":

> Your budget rules use the old filter and won't track spend — run reconfigure.

Then tell the user: "To fix this, choose reconfigure below, which will delete and recreate your rules using the current AGENT:STARTS_WITH:openclaw- filter."

Why this matters: After the D-07 migration, the agent ships --agent "openclaw-" on every transaction. The Revenium server matches budget rules by their AGENT filter dimension. Rules that filter AGENT:IS:OpenClaw look for an agent named exactly OpenClaw, but no transactions carry that name anymore — so the rules never fire, spend is never tracked, and budget enforcement is silently disabled. The user MUST reconfigure (via setup-guardrails.sh --interactive) to recreate rules with the new AGENT:STARTS_WITH:openclaw- filter. Repo edits cannot fix server-side rules.

Do NOT act unilaterally. Do NOT call setup-guardrails.sh without user request, do NOT delete or recreate any rule without explicit user action, and do NOT modify any rule in config.json. The user must choose to reconfigure (honors Phase 3 D-02, per D-08).

1. Persist the one-time flag. After surfacing the notice (or confirming no legacy rules exist), write "_legacyNoticeShown": true into ~/.openclaw/skills/revenium/config.json using an atomic temp-then-rename write so the notice does not repeat on subsequent /revenium invocations. Atomic write pattern (03-PATTERNS "Atomic JSON Write"):

```python

import json, os, tempfile

path = os.path.expanduser("~/.openclaw/skills/revenium/config.json")

with open(path, "r") as f:

cfg = json.load(f)

cfg["_legacyNoticeShown"] = True

tmp = path + ".tmp"

with open(tmp, "w") as f:

json.dump(cfg, f, indent=2)

f.write("\n")

os.replace(tmp, path)

```

Run this via a bash python3 -c invocation or execute_code — do NOT write the file with a text editor or cat/echo (not atomic).

1. Show rule IDs and per-rule state. Read ruleIds from ~/.openclaw/skills/revenium/config.json, then read per-rule state from ~/.openclaw/skills/revenium/guardrail-status.json. For each rule in rules[], display:
• Rule name
• state (ok / warn / block)
• currentValue vs hardLimit
• shadowMode (true = observe-only, not blocking)

1. Show autonomous mode and halt state. Read ~/.openclaw/skills/revenium/config.json and display:
• Autonomous mode: enabled or disabled
• Halt status: Read ~/.openclaw/skills/revenium/guardrail-status.json and check halted. Display "ACTIVE (since [haltedAt])" if halted is true, or "inactive" if false.
• If halt is active, also show: "To resume operations, run: bash ~/.openclaw/skills/revenium/scripts/clear-halt.sh"

1. Offer actions. Ask the user: "Would you like to reconfigure (change rules/settings) or done?"

• reconfigure: Run bash ~/.openclaw/skills/revenium/scripts/setup-guardrails.sh --interactive. The script handles delete-and-recreate of existing rules. Capture the exit code using the same contract as Setup Flow step 3 above.
• done: STOP — no further action.

If Setup Is NOT Complete (config.json missing, or ruleIds absent or [])

Run the Setup Flow from the Setup section above.

Troubleshooting

Binary Not Found

If revenium is not found on PATH:

• STOP all operations that require guardrail checking
• Tell the user: "The revenium CLI is not installed or not on your PATH. Install it from https://docs.revenium.io/for-ai-agents and ensure it is available in your shell."

API Key Invalid

If revenium config show reports no API key or an invalid key:

• STOP all operations that require guardrail checking
• Tell the user: "Your Revenium API key is missing or invalid inside the sandbox. The sandbox is authenticated via environment variables injected from your host's ~/.config/revenium/ config — it is NOT a live mount. Fix the credentials on the host: run revenium config set key (plus team-id, tenant-id, owner-id as needed) in your HOST terminal, then re-run bash ~/.openclaw/skills/revenium/scripts/post-install.sh and restart the gateway so the new credentials reach the sandbox. Then run /revenium to resume setup."

Network Errors

If any revenium CLI command fails due to network issues:

• Tell the user: "Unable to reach the Revenium API. Check your network connection and try again."
• Do NOT proceed with the operation until guardrail status is confirmed.

> Reminder: Check guardrail-status.json before your next response.