@zentropi/reflexes-openclaw 0.0.0-stage → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +127 -2
- package/dist/index.d.ts +345 -0
- package/dist/index.js +1161 -0
- package/dist/policy.d.ts +35 -0
- package/dist/policy.js +245 -0
- package/package.json +38 -3
package/dist/index.js
ADDED
|
@@ -0,0 +1,1161 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reflexes plugin for OpenClaw.
|
|
3
|
+
*
|
|
4
|
+
* Registers a `before_tool_call` hook that evaluates each tool call
|
|
5
|
+
* against plain-English Reflexes policies via a policy-steerable
|
|
6
|
+
* evaluator. Supports the Python reference's backends — `systemone` (the
|
|
7
|
+
* default: a System One decision model, Zentropi `cope-b-s1`, that evaluates
|
|
8
|
+
* all of a decision point's policies in one call), `zentropi` (CoPE single-
|
|
9
|
+
* label `/v1/label`), `openai`,
|
|
10
|
+
* `anthropic`, and `gemini` — selected by `evaluators.default.type`.
|
|
11
|
+
*
|
|
12
|
+
* Deny semantics (verified against openclaw 2026.6.11 source,
|
|
13
|
+
* tools-invoke-shared): a `{block: true, blockReason}` result surfaces
|
|
14
|
+
* to the model as a `tool_call_blocked` error whose message is the
|
|
15
|
+
* blockReason — so the policy text placed there drives self-correction,
|
|
16
|
+
* matching the Reflexes self-remediation protocol (SPEC.md §6).
|
|
17
|
+
*
|
|
18
|
+
* Failure mode: fail-open with a warning (SPEC.md §4 normative), same
|
|
19
|
+
* as the Python reference implementation.
|
|
20
|
+
*/
|
|
21
|
+
import { readFileSync } from "node:fs";
|
|
22
|
+
import { homedir } from "node:os";
|
|
23
|
+
import { join, dirname, resolve } from "node:path";
|
|
24
|
+
import { parse as parseYaml } from "yaml";
|
|
25
|
+
import { parseRef, resolveCriteria } from "./policy.js";
|
|
26
|
+
export { parseRef, resolveCriteria, stripFrontmatter, PolicyNotFound, _internal as policyInternal } from "./policy.js";
|
|
27
|
+
// ---- Diagnostic logging (config-driven, matches the Python regime) --------
|
|
28
|
+
// Level + format come from the `logging:` block in reflexes.yaml — no env
|
|
29
|
+
// vars. Default WARNING captures operational events (fail-open notices, skips,
|
|
30
|
+
// `log`-action hits) with no message content; message CONTENT is emitted ONLY
|
|
31
|
+
// at `debug` (via rxdebug), mirroring the Python hook. `off` silences all,
|
|
32
|
+
// `json` structures. Every line is host-tagged (`openclaw`) so it stays
|
|
33
|
+
// attributable in aggregated/shared logs.
|
|
34
|
+
const _LOG_ORDER = { off: 0, error: 1, warning: 2, info: 3, debug: 4 };
|
|
35
|
+
const _LOG_HOST = "openclaw";
|
|
36
|
+
let _logThreshold = _LOG_ORDER.warning;
|
|
37
|
+
let _logFormat = "text";
|
|
38
|
+
function configureLogging(doc) {
|
|
39
|
+
const block = (doc?.logging ?? {}) || {};
|
|
40
|
+
const level = String(block.level ?? "warning").trim().toLowerCase();
|
|
41
|
+
const fmt = String(block.format ?? "text").trim().toLowerCase();
|
|
42
|
+
// Fail safe: an unknown level never resolves more verbose than the default.
|
|
43
|
+
_logThreshold = level in _LOG_ORDER ? _LOG_ORDER[level] : _LOG_ORDER.warning;
|
|
44
|
+
_logFormat = fmt === "json" ? "json" : "text";
|
|
45
|
+
}
|
|
46
|
+
// All Reflexes plugin logs funnel through here so the config level/format/host
|
|
47
|
+
// govern them uniformly.
|
|
48
|
+
function _emit(levelName, levelNum, msg) {
|
|
49
|
+
if (levelNum > _logThreshold)
|
|
50
|
+
return;
|
|
51
|
+
// The host tag identifies the subsystem already, so drop a redundant inline
|
|
52
|
+
// `[reflexes]` prefix on operational messages (avoids `[openclaw] [reflexes] …`).
|
|
53
|
+
const clean = msg.replace(/^\[reflexes\]\s*/, "");
|
|
54
|
+
if (_logFormat === "json") {
|
|
55
|
+
console.warn(JSON.stringify({ level: levelName, logger: "reflexes", host: _LOG_HOST, message: clean }));
|
|
56
|
+
}
|
|
57
|
+
else {
|
|
58
|
+
console.warn(`[${_LOG_HOST}] ${clean}`);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
function rxwarn(msg) {
|
|
62
|
+
_emit("WARNING", _LOG_ORDER.warning, msg);
|
|
63
|
+
}
|
|
64
|
+
// Content-bearing lines go here — gated at debug so nothing sensitive is
|
|
65
|
+
// captured unless the operator opts in (parity with the Python hook).
|
|
66
|
+
function rxdebug(msg) {
|
|
67
|
+
_emit("DEBUG", _LOG_ORDER.debug, msg);
|
|
68
|
+
}
|
|
69
|
+
function _truncForLog(s, n = 200) {
|
|
70
|
+
return s.length > n ? `${s.slice(0, n)}…` : s;
|
|
71
|
+
}
|
|
72
|
+
const DEFAULT_CONFIG_PATHS = [
|
|
73
|
+
join(homedir(), ".reflexes", "reflexes.yaml"),
|
|
74
|
+
join(process.cwd(), "reflexes.yaml"),
|
|
75
|
+
];
|
|
76
|
+
/**
|
|
77
|
+
* A policy IS its criteria: the whole document is sent to the evaluator. A
|
|
78
|
+
* leading YAML frontmatter block, if present, is optional metadata and is
|
|
79
|
+
* stripped. Mirrors reflexes.document.parse (SPEC §3).
|
|
80
|
+
*/
|
|
81
|
+
export function extractCriteria(markdown) {
|
|
82
|
+
return markdown.replace(/^\s*---\s*\n[\s\S]*?\n---\s*\n/, "").trim();
|
|
83
|
+
}
|
|
84
|
+
export function loadConfig(configPath) {
|
|
85
|
+
const candidates = configPath ? [configPath] : DEFAULT_CONFIG_PATHS;
|
|
86
|
+
for (const path of candidates) {
|
|
87
|
+
let raw;
|
|
88
|
+
try {
|
|
89
|
+
raw = readFileSync(path, "utf8");
|
|
90
|
+
}
|
|
91
|
+
catch {
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
const doc = parseYaml(raw);
|
|
95
|
+
// Set the logging level/format from the `logging:` block before we emit
|
|
96
|
+
// anything, so `off` can silence even the DISABLED notice below.
|
|
97
|
+
configureLogging(doc);
|
|
98
|
+
// Global kill switch: a top-level `enabled: false` turns the whole system
|
|
99
|
+
// off — no bindings load, every hook no-ops. Say so loudly (the doctor is the
|
|
100
|
+
// Python-side loud surface; this is OpenClaw's).
|
|
101
|
+
const disabled = doc?.enabled === false;
|
|
102
|
+
if (disabled) {
|
|
103
|
+
rxwarn(`[reflexes] DISABLED — \`enabled: false\` in ${path}; NO policies are enforced. ` +
|
|
104
|
+
"Set `enabled: true` (or remove the line) and restart to re-enable.");
|
|
105
|
+
}
|
|
106
|
+
const groups = (disabled ? {} : (doc?.reflexes ?? {}));
|
|
107
|
+
const bindings = [];
|
|
108
|
+
for (const entries of Object.values(groups)) {
|
|
109
|
+
for (const entry of entries ?? []) {
|
|
110
|
+
// Triggers OpenClaw can enforce: on_input (before_agent_run gate),
|
|
111
|
+
// before_tool_call (tool hook), before_response (before_agent_finalize).
|
|
112
|
+
// after_tool_call is observe-only on OpenClaw — warn rather than silently
|
|
113
|
+
// drop it, so an operator doesn't think it's enforcing.
|
|
114
|
+
if (entry.trigger !== "on_input" &&
|
|
115
|
+
entry.trigger !== "before_tool_call" &&
|
|
116
|
+
entry.trigger !== "before_response") {
|
|
117
|
+
rxwarn(`[reflexes] policy "${entry.name ?? entry.policy}" binds trigger ` +
|
|
118
|
+
`"${entry.trigger}", which OpenClaw can't enforce (after_tool_call is ` +
|
|
119
|
+
`observe-only) — skipping. Use before_tool_call for tool-side enforcement.`);
|
|
120
|
+
continue;
|
|
121
|
+
}
|
|
122
|
+
const ref = parseRef(entry.policy);
|
|
123
|
+
const baseDir = dirname(path);
|
|
124
|
+
// `name` is a required binding field; fall back to the file basename for
|
|
125
|
+
// local file refs (hosted refs have no filename to derive from).
|
|
126
|
+
const name = entry.name ??
|
|
127
|
+
(ref.scheme === "file" ? ref.locator.split("/").pop()?.replace(/\.md$/, "") : undefined);
|
|
128
|
+
if (!name) {
|
|
129
|
+
rxwarn(`[reflexes] binding for '${entry.policy}' is missing 'name', skipping`);
|
|
130
|
+
continue;
|
|
131
|
+
}
|
|
132
|
+
// Read local files eagerly (fail-fast, no async at load). Hosted refs
|
|
133
|
+
// (zentropi:/github:) resolve lazily on first evaluation + cache — see
|
|
134
|
+
// resolveBindingCriteria.
|
|
135
|
+
let criteria = "";
|
|
136
|
+
if (ref.scheme === "file") {
|
|
137
|
+
const policyPath = resolve(baseDir, ref.locator);
|
|
138
|
+
try {
|
|
139
|
+
criteria = extractCriteria(readFileSync(policyPath, "utf8"));
|
|
140
|
+
}
|
|
141
|
+
catch {
|
|
142
|
+
rxwarn(`[reflexes] policy not readable, skipping: ${policyPath}`);
|
|
143
|
+
continue;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
bindings.push({
|
|
147
|
+
policy: ref.raw,
|
|
148
|
+
trigger: entry.trigger,
|
|
149
|
+
action: entry.action ?? "deny",
|
|
150
|
+
criteria,
|
|
151
|
+
name,
|
|
152
|
+
ref,
|
|
153
|
+
baseDir,
|
|
154
|
+
});
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
const evalCfg = doc?.evaluators?.default ?? {};
|
|
158
|
+
const evalType = (evalCfg.type ?? "systemone").toLowerCase();
|
|
159
|
+
// Per-type defaults mirror the Python evaluator classes. `apiBase` is the
|
|
160
|
+
// base URL for zentropi (evaluate() appends /v1/label) and the models base
|
|
161
|
+
// for gemini; for openai/anthropic it is the full endpoint URL. `endpoint`
|
|
162
|
+
// is accepted as an alias (the field name the Python reflexes.yaml uses).
|
|
163
|
+
const EVAL_DEFAULTS = {
|
|
164
|
+
zentropi: { apiBase: "https://api.zentropi.ai", keyEnv: "ZENTROPI_API_KEY" },
|
|
165
|
+
cope: { apiBase: "https://api.zentropi.ai", keyEnv: "ZENTROPI_API_KEY" },
|
|
166
|
+
openai: { apiBase: "https://api.openai.com/v1/chat/completions", keyEnv: "OPENAI_API_KEY" },
|
|
167
|
+
anthropic: { apiBase: "https://api.anthropic.com/v1/messages", keyEnv: "ANTHROPIC_API_KEY" },
|
|
168
|
+
gemini: { apiBase: "https://generativelanguage.googleapis.com/v1beta/models", keyEnv: "GEMINI_API_KEY" },
|
|
169
|
+
// System One decision models (multi-label, one call) — the default.
|
|
170
|
+
// apiBase is the full /v1/systemone endpoint; default is cope-b-s1 on
|
|
171
|
+
// Zentropi (swap model + endpoint for jev-latest on OpenRouter, etc.).
|
|
172
|
+
systemone: { apiBase: "https://api.zentropi.ai/v1/systemone", keyEnv: "ZENTROPI_API_KEY" },
|
|
173
|
+
};
|
|
174
|
+
const d = EVAL_DEFAULTS[evalType] ?? EVAL_DEFAULTS.zentropi;
|
|
175
|
+
return {
|
|
176
|
+
bindings,
|
|
177
|
+
evaluator: {
|
|
178
|
+
type: evalType,
|
|
179
|
+
model: evalCfg.model,
|
|
180
|
+
apiBase: evalCfg.api_base ?? evalCfg.endpoint ?? d.apiBase,
|
|
181
|
+
apiKeyEnv: evalCfg.api_key_env ?? d.keyEnv,
|
|
182
|
+
},
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
return null;
|
|
186
|
+
}
|
|
187
|
+
/** Resolve a binding's criteria on demand, memoizing the result. File refs are
|
|
188
|
+
* already resolved at load; hosted refs (zentropi:/github:) fetch + cache on
|
|
189
|
+
* first use, then reuse the cached value (so denyReason/reviseInstruction, which
|
|
190
|
+
* read binding.criteria, see the resolved text). */
|
|
191
|
+
export async function resolveBindingCriteria(binding, fetchImpl) {
|
|
192
|
+
if (binding.criteria)
|
|
193
|
+
return binding.criteria;
|
|
194
|
+
const criteria = await resolveCriteria(binding.ref, { baseDir: binding.baseDir, fetchImpl });
|
|
195
|
+
binding.criteria = criteria; // memoize
|
|
196
|
+
return criteria;
|
|
197
|
+
}
|
|
198
|
+
/** Serialize the pending tool call as the SPEC §5 JSON shape — matches the
|
|
199
|
+
* Python reference and every other host: `{"tool_name": ..., "args": ...}`. */
|
|
200
|
+
export function toolCallContent(event) {
|
|
201
|
+
return JSON.stringify({ tool_name: event.toolName, args: event.params ?? {} });
|
|
202
|
+
}
|
|
203
|
+
// --- Task-context assembly ------------------------------------------------
|
|
204
|
+
// Mirrors the Python reference (reflexes._context.assemble_task_context +
|
|
205
|
+
// reflexes.core._assemble_content) byte-for-byte, so the evaluator receives
|
|
206
|
+
// identical input on every host. Section labels per SPEC §5.1.
|
|
207
|
+
// Per-section char budgets, weighted so a large AGENTS.md can't starve the
|
|
208
|
+
// current request (matches reflexes._context).
|
|
209
|
+
const PRIMARY_PROMPT_MAX = 4000;
|
|
210
|
+
const INITIAL_PROMPT_MAX = 1500;
|
|
211
|
+
const STANDING_INSTRUCTIONS_MAX = 1500;
|
|
212
|
+
function truncate(text, maxChars) {
|
|
213
|
+
return text.length <= maxChars
|
|
214
|
+
? text
|
|
215
|
+
: text.slice(0, maxChars).trimEnd() + "\n[...truncated]";
|
|
216
|
+
}
|
|
217
|
+
/** Assemble the labeled task-context block (SPEC §5.1); "" if nothing given.
|
|
218
|
+
* Mirrors reflexes._context.assemble_task_context. */
|
|
219
|
+
export function assembleTaskContext(src) {
|
|
220
|
+
const sections = [];
|
|
221
|
+
const current = src.currentRequest?.trim();
|
|
222
|
+
const original = src.originalTask?.trim();
|
|
223
|
+
const standing = src.standingInstructions?.trim();
|
|
224
|
+
if (current) {
|
|
225
|
+
sections.push(`Current request:\n${truncate(current, PRIMARY_PROMPT_MAX)}`);
|
|
226
|
+
}
|
|
227
|
+
if (original && original !== (current ?? "")) {
|
|
228
|
+
sections.push(`Original task:\n${truncate(original, INITIAL_PROMPT_MAX)}`);
|
|
229
|
+
}
|
|
230
|
+
if (standing) {
|
|
231
|
+
sections.push(`Standing instructions:\n${truncate(standing, STANDING_INSTRUCTIONS_MAX)}`);
|
|
232
|
+
}
|
|
233
|
+
return sections.join("\n\n");
|
|
234
|
+
}
|
|
235
|
+
/** Frame content + context for the evaluator. Mirrors
|
|
236
|
+
* reflexes.core._assemble_content byte-for-byte. */
|
|
237
|
+
export function assembleContent(content, context, checkType = "Content", contextLabel = "User request") {
|
|
238
|
+
if (!context)
|
|
239
|
+
return content;
|
|
240
|
+
return (`Evaluate the ${checkType} below against the policy. ` +
|
|
241
|
+
`The ${contextLabel} is provided for reference — evaluate the ${checkType}, not the ${contextLabel}.\n\n` +
|
|
242
|
+
`${contextLabel}: ${context}\n\n` +
|
|
243
|
+
`${checkType}: ${content}`);
|
|
244
|
+
}
|
|
245
|
+
// --- OpenClaw carry-over -----------------------------------------------------
|
|
246
|
+
// The `before_tool_call` event has no conversation. But `llm_input` fires
|
|
247
|
+
// earlier in the same run (same `runId`) and carries both the user's request
|
|
248
|
+
// (`prompt`) and the assembled system prompt (`systemPrompt`). We stash those
|
|
249
|
+
// in OpenClaw's per-run store (`api.runContext`, keyed by `runId`, auto-cleared
|
|
250
|
+
// on run end) and read them back in `before_tool_call`. Signatures verified
|
|
251
|
+
// against openclaw 2026.6.11 (`OpenClawPluginApi`, `PluginHookLlmInputEvent`,
|
|
252
|
+
// `OpenClawPluginRunContextApi`).
|
|
253
|
+
/** runContext namespace for the stashed request. */
|
|
254
|
+
const REFLEXES_NS = "reflexes/current-request";
|
|
255
|
+
/** Capture hook: stash this run's request + system prompt (best-effort). */
|
|
256
|
+
export function rememberRequest(api, event) {
|
|
257
|
+
if (!event.runId || typeof event.prompt !== "string")
|
|
258
|
+
return;
|
|
259
|
+
const value = { prompt: event.prompt, systemPrompt: event.systemPrompt };
|
|
260
|
+
try {
|
|
261
|
+
api.runContext.setRunContext({ runId: event.runId, namespace: REFLEXES_NS, value });
|
|
262
|
+
}
|
|
263
|
+
catch {
|
|
264
|
+
// best-effort; enforcement still runs with the disk standing-instructions fallback
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
// --- Original task (session-scoped) -----------------------------------------
|
|
268
|
+
// The first inbound message of a session is the "Original task". Unlike the
|
|
269
|
+
// per-run request it persists across turns, so it lives in a module map keyed
|
|
270
|
+
// by sessionKey — captured from message_received (robust to compaction, which
|
|
271
|
+
// can drop the first message from historyMessages) and evicted on session_end.
|
|
272
|
+
const originalTaskBySession = new Map();
|
|
273
|
+
const ORIGINAL_TASK_MAX_SESSIONS = 500; // backstop if session_end never fires
|
|
274
|
+
/** Capture hook: remember the first inbound message of a session. */
|
|
275
|
+
export function rememberOriginalTask(event) {
|
|
276
|
+
const key = event.sessionKey;
|
|
277
|
+
const content = typeof event.content === "string" ? event.content.trim() : "";
|
|
278
|
+
if (!key || !content || originalTaskBySession.has(key))
|
|
279
|
+
return;
|
|
280
|
+
if (originalTaskBySession.size >= ORIGINAL_TASK_MAX_SESSIONS) {
|
|
281
|
+
const oldest = originalTaskBySession.keys().next().value; // Map is insertion-ordered
|
|
282
|
+
if (oldest !== undefined)
|
|
283
|
+
originalTaskBySession.delete(oldest);
|
|
284
|
+
}
|
|
285
|
+
originalTaskBySession.set(key, content);
|
|
286
|
+
}
|
|
287
|
+
const upgradeNoticeBySession = new Map();
|
|
288
|
+
const UPGRADE_NOTICE_MAX_SESSIONS = 500; // backstop if session_end never fires
|
|
289
|
+
/** Record a fail-open upgrade notice for this session (first one wins — once
|
|
290
|
+
* per session). No-op without a sessionKey (nothing to correlate on). */
|
|
291
|
+
export function rememberUpgradeNotice(sessionKey, notice) {
|
|
292
|
+
if (!sessionKey || upgradeNoticeBySession.has(sessionKey))
|
|
293
|
+
return;
|
|
294
|
+
if (upgradeNoticeBySession.size >= UPGRADE_NOTICE_MAX_SESSIONS) {
|
|
295
|
+
const oldest = upgradeNoticeBySession.keys().next().value; // insertion-ordered
|
|
296
|
+
if (oldest !== undefined)
|
|
297
|
+
upgradeNoticeBySession.delete(oldest);
|
|
298
|
+
}
|
|
299
|
+
upgradeNoticeBySession.set(sessionKey, { notice, surfaced: false });
|
|
300
|
+
}
|
|
301
|
+
/** Return this session's pending notice the first time it's read, then mark it
|
|
302
|
+
* surfaced so it lands on exactly one reply. */
|
|
303
|
+
export function takeUpgradeNotice(sessionKey) {
|
|
304
|
+
if (!sessionKey)
|
|
305
|
+
return null;
|
|
306
|
+
const state = upgradeNoticeBySession.get(sessionKey);
|
|
307
|
+
if (!state || state.surfaced)
|
|
308
|
+
return null;
|
|
309
|
+
state.surfaced = true;
|
|
310
|
+
return state.notice;
|
|
311
|
+
}
|
|
312
|
+
/** Inject the fail-open upgrade notice into the model's NEXT turn, so the agent
|
|
313
|
+
* itself learns enforcement was degraded — independent of any outbound channel
|
|
314
|
+
* (unlike the user-facing reply footer). Uses OpenClaw's next-turn-injection
|
|
315
|
+
* seam, deduped once per session by idempotencyKey. Fire-and-forget and fully
|
|
316
|
+
* guarded: an injection failure (or a gateway without the API) must never
|
|
317
|
+
* break the agent loop. */
|
|
318
|
+
/** Enqueue model-visible text for the next turn (OpenClaw's integrity-safe
|
|
319
|
+
* agent channel — never touches the current reply). Advisory; never throws. */
|
|
320
|
+
export function enqueueAgentText(api, sessionKey, text, idempotencyKey) {
|
|
321
|
+
if (!sessionKey)
|
|
322
|
+
return;
|
|
323
|
+
try {
|
|
324
|
+
const enqueue = api?.session?.workflow?.enqueueNextTurnInjection;
|
|
325
|
+
if (typeof enqueue !== "function")
|
|
326
|
+
return;
|
|
327
|
+
const result = enqueue.call(api.session.workflow, { sessionKey, text, idempotencyKey });
|
|
328
|
+
// Swallow async rejection — advisory only.
|
|
329
|
+
if (result && typeof result.then === "function") {
|
|
330
|
+
result.then(undefined, () => { });
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
catch {
|
|
334
|
+
// Never break the agent on an injection failure.
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
export function enqueueAgentNotice(api, sessionKey, upgrade) {
|
|
338
|
+
enqueueAgentText(api, sessionKey, upgrade.agentNotice, `reflexes-upgrade:${sessionKey}`);
|
|
339
|
+
}
|
|
340
|
+
/** Agent-facing note for a `flag` match — surfaced via the next-turn injection
|
|
341
|
+
* so `flag` is observable to the model (not just the operator log), matching
|
|
342
|
+
* the `additionalContext` flag notes on Claude Code / Codex. */
|
|
343
|
+
export function flagNote(binding, verdict, subject) {
|
|
344
|
+
const conf = verdict.confidence !== undefined ? ` (confidence ${verdict.confidence})` : "";
|
|
345
|
+
return `[Reflexes] The "${binding.name}" policy flagged your ${subject}${conf}. It was allowed, not blocked — take the flag into account going forward.`;
|
|
346
|
+
}
|
|
347
|
+
/** Outbound hook: surface this session's pending fail-open upgrade notice as a
|
|
348
|
+
* distinct `context` (footer) block on the reply the user sees, once per
|
|
349
|
+
* session. This is the one reliable user-visible surface on OpenClaw —
|
|
350
|
+
* context/prompt hooks are model-facing only (see FRAMEWORKS.md OpenClaw
|
|
351
|
+
* notes).
|
|
352
|
+
*
|
|
353
|
+
* The model's response is never mutated or dropped:
|
|
354
|
+
* - When the reply already carries a presentation, we append the notice as a
|
|
355
|
+
* trailing context block and copy every existing block/field unchanged.
|
|
356
|
+
* - When the reply is plain text, we wrap that text VERBATIM in a `text`
|
|
357
|
+
* block and add the context block after it. The model's words become the
|
|
358
|
+
* single source of truth (the presentation), so we drop the now-redundant
|
|
359
|
+
* top-level `text` to avoid double-rendering on channels that show both
|
|
360
|
+
* (e.g. Teams); core regenerates plain-channel fallback text from these
|
|
361
|
+
* blocks (message-presentation.md degradation rules: `text` blocks render
|
|
362
|
+
* as paragraphs, `context` blocks as compact lines).
|
|
363
|
+
*
|
|
364
|
+
* Returns a NEW payload object; the input event.payload is never mutated. */
|
|
365
|
+
export function appendUpgradeNotice(event, ctx) {
|
|
366
|
+
const notice = takeUpgradeNotice(ctx?.sessionKey ?? event?.sessionKey);
|
|
367
|
+
if (!notice)
|
|
368
|
+
return undefined;
|
|
369
|
+
const payload = event?.payload;
|
|
370
|
+
if (!payload || typeof payload !== "object")
|
|
371
|
+
return undefined;
|
|
372
|
+
const contextBlock = { type: "context", text: notice };
|
|
373
|
+
const existing = payload.presentation;
|
|
374
|
+
// Case 1: reply already has a presentation — append, copying everything else.
|
|
375
|
+
if (existing && Array.isArray(existing.blocks)) {
|
|
376
|
+
return {
|
|
377
|
+
payload: {
|
|
378
|
+
...payload,
|
|
379
|
+
presentation: { ...existing, blocks: [...existing.blocks, contextBlock] },
|
|
380
|
+
},
|
|
381
|
+
};
|
|
382
|
+
}
|
|
383
|
+
// Case 2: plain-text reply — wrap the model's text verbatim, then the notice.
|
|
384
|
+
const modelText = typeof payload.text === "string" ? payload.text : "";
|
|
385
|
+
if (!modelText) {
|
|
386
|
+
// No text and no presentation (e.g. media-only): attach a context-only
|
|
387
|
+
// presentation so the notice still surfaces; other fields pass through.
|
|
388
|
+
return { payload: { ...payload, presentation: { blocks: [contextBlock] } } };
|
|
389
|
+
}
|
|
390
|
+
const { text: _redundant, ...rest } = payload;
|
|
391
|
+
return {
|
|
392
|
+
payload: {
|
|
393
|
+
...rest,
|
|
394
|
+
presentation: { blocks: [{ type: "text", text: modelText }, contextBlock] },
|
|
395
|
+
},
|
|
396
|
+
};
|
|
397
|
+
}
|
|
398
|
+
export function forgetSession(event) {
|
|
399
|
+
if (event.sessionKey) {
|
|
400
|
+
originalTaskBySession.delete(event.sessionKey);
|
|
401
|
+
upgradeNoticeBySession.delete(event.sessionKey);
|
|
402
|
+
}
|
|
403
|
+
}
|
|
404
|
+
function recallOriginalTask(ctx) {
|
|
405
|
+
const key = ctx?.sessionKey;
|
|
406
|
+
return key ? originalTaskBySession.get(key) ?? null : null;
|
|
407
|
+
}
|
|
408
|
+
/** Read the run's stashed request + the session's original task as task-context
|
|
409
|
+
* sources, or undefined if neither is available. */
|
|
410
|
+
export function recallTaskContext(api, ctx) {
|
|
411
|
+
let captured;
|
|
412
|
+
const runId = ctx?.runId;
|
|
413
|
+
if (runId) {
|
|
414
|
+
try {
|
|
415
|
+
captured = api.runContext.getRunContext({ runId, namespace: REFLEXES_NS });
|
|
416
|
+
}
|
|
417
|
+
catch {
|
|
418
|
+
captured = undefined;
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
const currentRequest = captured && typeof captured.prompt === "string" ? captured.prompt : null;
|
|
422
|
+
const standingInstructions = captured?.systemPrompt ?? null;
|
|
423
|
+
const originalTask = recallOriginalTask(ctx);
|
|
424
|
+
if (!currentRequest && !standingInstructions && !originalTask)
|
|
425
|
+
return undefined;
|
|
426
|
+
const out = { currentRequest, standingInstructions };
|
|
427
|
+
if (originalTask)
|
|
428
|
+
out.originalTask = originalTask;
|
|
429
|
+
return out;
|
|
430
|
+
}
|
|
431
|
+
// --- Trajectory ("Actions this turn") ---------------------------------------
|
|
432
|
+
// before_tool_call/before_agent_finalize don't carry what the agent DID this
|
|
433
|
+
// turn. Accumulate it from after_tool_call into the same per-run store, and
|
|
434
|
+
// append it as the "Actions this turn:" section for before_response policies
|
|
435
|
+
// (Early-Stopping / Laziness-Detection) — matching the Claude Code trajectory.
|
|
436
|
+
const REFLEXES_TRAJECTORY_NS = "reflexes/trajectory";
|
|
437
|
+
const TRAJECTORY_MAX_ENTRIES = 50; // cap so a long turn can't bloat the context
|
|
438
|
+
const TRAJECTORY_ARG_MAX = 120;
|
|
439
|
+
/** Pull a readable primary argument from a tool call's params. */
|
|
440
|
+
function primaryArg(params) {
|
|
441
|
+
if (!params)
|
|
442
|
+
return null;
|
|
443
|
+
for (const key of ["command", "file_path", "path", "query", "url", "pattern"]) {
|
|
444
|
+
const v = params[key];
|
|
445
|
+
if (typeof v === "string" && v.trim())
|
|
446
|
+
return v;
|
|
447
|
+
}
|
|
448
|
+
for (const v of Object.values(params)) {
|
|
449
|
+
if (typeof v === "string" && v.trim())
|
|
450
|
+
return v;
|
|
451
|
+
}
|
|
452
|
+
return null;
|
|
453
|
+
}
|
|
454
|
+
/** Render one completed tool call as a trajectory line. */
|
|
455
|
+
export function renderAction(event) {
|
|
456
|
+
const arg = primaryArg(event.params);
|
|
457
|
+
const head = arg ? `${event.toolName}: ${truncate(arg, TRAJECTORY_ARG_MAX)}` : event.toolName;
|
|
458
|
+
return event.error ? `${head} ✗ ${truncate(String(event.error), TRAJECTORY_ARG_MAX)}` : `${head} ✓`;
|
|
459
|
+
}
|
|
460
|
+
/** Capture hook: append this completed tool call to the run's trajectory. */
|
|
461
|
+
export function rememberAction(api, event, ctx) {
|
|
462
|
+
const runId = event.runId ?? ctx?.runId;
|
|
463
|
+
if (!runId)
|
|
464
|
+
return;
|
|
465
|
+
try {
|
|
466
|
+
const prev = api.runContext.getRunContext({ runId, namespace: REFLEXES_TRAJECTORY_NS });
|
|
467
|
+
const lines = Array.isArray(prev) ? prev : [];
|
|
468
|
+
lines.push(renderAction(event));
|
|
469
|
+
const capped = lines.slice(-TRAJECTORY_MAX_ENTRIES);
|
|
470
|
+
api.runContext.setRunContext({ runId, namespace: REFLEXES_TRAJECTORY_NS, value: capped });
|
|
471
|
+
}
|
|
472
|
+
catch {
|
|
473
|
+
// best-effort; before_response still runs without the trajectory
|
|
474
|
+
}
|
|
475
|
+
}
|
|
476
|
+
/** Read the run's trajectory back as an "Actions this turn:" block, or null. */
|
|
477
|
+
export function recallTrajectory(api, ctx) {
|
|
478
|
+
const runId = ctx?.runId;
|
|
479
|
+
if (!runId)
|
|
480
|
+
return null;
|
|
481
|
+
let lines = [];
|
|
482
|
+
try {
|
|
483
|
+
const stored = api.runContext.getRunContext({ runId, namespace: REFLEXES_TRAJECTORY_NS });
|
|
484
|
+
if (Array.isArray(stored))
|
|
485
|
+
lines = stored.filter((l) => typeof l === "string");
|
|
486
|
+
}
|
|
487
|
+
catch {
|
|
488
|
+
return null;
|
|
489
|
+
}
|
|
490
|
+
if (lines.length === 0)
|
|
491
|
+
return null;
|
|
492
|
+
return "Actions this turn:\n" + lines.map((l) => ` ${l}`).join("\n");
|
|
493
|
+
}
|
|
494
|
+
/** Resolve project standing instructions from disk (AGENTS.md, else CLAUDE.md)
|
|
495
|
+
* at `cwd`. Independent of the event, so it works even when OpenClaw doesn't
|
|
496
|
+
* surface the conversation. null if none present. */
|
|
497
|
+
export function resolveStandingInstructions(cwd) {
|
|
498
|
+
for (const name of ["AGENTS.md", "CLAUDE.md"]) {
|
|
499
|
+
try {
|
|
500
|
+
const body = readFileSync(join(cwd, name), "utf8").trim();
|
|
501
|
+
if (body)
|
|
502
|
+
return body;
|
|
503
|
+
}
|
|
504
|
+
catch {
|
|
505
|
+
// not present / unreadable — try the next
|
|
506
|
+
}
|
|
507
|
+
}
|
|
508
|
+
return null;
|
|
509
|
+
}
|
|
510
|
+
// --- Fail-open upgrade signal ------------------------------------------------
|
|
511
|
+
// Mirrors the Python evaluator's _synthesize_upgrade. The deployed API returns
|
|
512
|
+
// plain error bodies (no tier envelope), so we synthesize the upgrade
|
|
513
|
+
// condition from the status code: a sustained 429 (rate limit) or a 403
|
|
514
|
+
// (subscriber-only capability). Unlike a generic failure, this carries a
|
|
515
|
+
// user-facing notice the message_sending hook appends to the reply — OpenClaw's
|
|
516
|
+
// context/prompt channels are model-facing only, so the reply is the only
|
|
517
|
+
// reliable way to tell the human enforcement was degraded.
|
|
518
|
+
const UPGRADE_URL = "https://zentropi.ai/subscription";
|
|
519
|
+
const SUPPORT_EMAIL = "info@zentropi.ai";
|
|
520
|
+
const COPE_MODEL_CARD = "https://huggingface.co/zentropi-ai/cope-b-a4b";
|
|
521
|
+
// Transient server conditions worth an immediate retry (mirrors the Python
|
|
522
|
+
// evaluator's RETRYABLE_STATUS_CODES + RETRY_DELAYS). A 429 only becomes an
|
|
523
|
+
// upgrade signal if it survives every retry — a sustained limit, not a blip.
|
|
524
|
+
const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 529]);
|
|
525
|
+
const RETRY_DELAYS_MS = [0, 100, 1000];
|
|
526
|
+
const MAX_RETRIES = 3;
|
|
527
|
+
export class UpgradeRequired extends Error {
|
|
528
|
+
kind;
|
|
529
|
+
/** One-line notice shown to the user (appended to the outbound reply). */
|
|
530
|
+
userNotice;
|
|
531
|
+
/** Notice injected into the model's next turn, so the agent itself learns
|
|
532
|
+
* enforcement was degraded even when there's no outbound channel. */
|
|
533
|
+
agentNotice;
|
|
534
|
+
constructor(kind, userNotice, agentNotice) {
|
|
535
|
+
super(userNotice);
|
|
536
|
+
this.name = "UpgradeRequired";
|
|
537
|
+
this.kind = kind;
|
|
538
|
+
this.userNotice = userNotice;
|
|
539
|
+
this.agentNotice = agentNotice;
|
|
540
|
+
}
|
|
541
|
+
}
|
|
542
|
+
function synthesizeUpgrade(status) {
|
|
543
|
+
if (status === 403) {
|
|
544
|
+
return new UpgradeRequired("subscription", `⚠️ Reflexes: a policy couldn't be checked — this evaluation requires a ` +
|
|
545
|
+
`Zentropi subscription, so enforcement is degraded for this turn. ` +
|
|
546
|
+
`Subscribe at ${UPGRADE_URL} (or email ${SUPPORT_EMAIL}).`, `[REFLEXES] A policy check on your recent action could not run — the ` +
|
|
547
|
+
`evaluation requires a Zentropi subscription. The action proceeded ` +
|
|
548
|
+
`WITHOUT that check (fail-open), so enforcement is degraded this turn. ` +
|
|
549
|
+
`Proceed cautiously; if relevant, tell the user enforcement is ` +
|
|
550
|
+
`temporarily degraded (they can subscribe at ${UPGRADE_URL}).`);
|
|
551
|
+
}
|
|
552
|
+
return new UpgradeRequired("rate_limit", `⚠️ Reflexes: a policy couldn't be checked — the Zentropi rate limit was ` +
|
|
553
|
+
`reached, so enforcement is degraded for this turn. Raise the limit at ` +
|
|
554
|
+
`${UPGRADE_URL}, or self-host the open CoPE model for no rate limits at ` +
|
|
555
|
+
`all (${COPE_MODEL_CARD}).`, `[REFLEXES] A policy check on your recent action could not run — the ` +
|
|
556
|
+
`Zentropi evaluator is rate-limited. The action proceeded WITHOUT that ` +
|
|
557
|
+
`check (fail-open), so enforcement is degraded this turn. Proceed ` +
|
|
558
|
+
`cautiously; if relevant, tell the user enforcement is temporarily ` +
|
|
559
|
+
`degraded (they can raise limits at ${UPGRADE_URL} or self-host the open ` +
|
|
560
|
+
`CoPE model: ${COPE_MODEL_CARD}).`);
|
|
561
|
+
}
|
|
562
|
+
const retryDelay = (attempt) => RETRY_DELAYS_MS[Math.min(attempt, RETRY_DELAYS_MS.length - 1)];
|
|
563
|
+
const sleep = (ms) => ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
|
|
564
|
+
/** Dispatch to the configured evaluator backend. Mirrors the Python
|
|
565
|
+
* reference's four evaluator classes (reflexes/evaluators/*.py) — same
|
|
566
|
+
* endpoints, prompts, and label parsing — so a reflexes.yaml behaves
|
|
567
|
+
* identically whether evaluated by the Python integration or this plugin. */
|
|
568
|
+
export async function evaluate(config, criteria, content, opts = {}) {
|
|
569
|
+
const type = (config.evaluator.type ?? "systemone").toLowerCase();
|
|
570
|
+
if (type === "openai")
|
|
571
|
+
return evaluateOpenAICompatible(config, criteria, content, opts);
|
|
572
|
+
if (type === "anthropic")
|
|
573
|
+
return evaluateAnthropic(config, criteria, content, opts);
|
|
574
|
+
if (type === "gemini")
|
|
575
|
+
return evaluateGemini(config, criteria, content, opts);
|
|
576
|
+
if (type === "systemone")
|
|
577
|
+
return evaluateSystemOne(config, criteria, content, opts);
|
|
578
|
+
return evaluateZentropi(config, criteria, content, opts); // zentropi / cope / default
|
|
579
|
+
}
|
|
580
|
+
async function evaluateZentropi(config, criteria, content, opts = {}) {
|
|
581
|
+
const doFetch = opts.fetchImpl ?? fetch;
|
|
582
|
+
const apiKey = process.env[config.evaluator.apiKeyEnv];
|
|
583
|
+
let lastStatus;
|
|
584
|
+
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
|
|
585
|
+
const controller = new AbortController();
|
|
586
|
+
const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 10_000);
|
|
587
|
+
let res;
|
|
588
|
+
try {
|
|
589
|
+
res = await doFetch(`${config.evaluator.apiBase}/v1/label`, {
|
|
590
|
+
method: "POST",
|
|
591
|
+
headers: {
|
|
592
|
+
"Content-Type": "application/json",
|
|
593
|
+
...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
|
|
594
|
+
},
|
|
595
|
+
body: JSON.stringify({
|
|
596
|
+
model: config.evaluator.model ?? "cope-latest",
|
|
597
|
+
criteria_text: criteria,
|
|
598
|
+
content_text: content,
|
|
599
|
+
}),
|
|
600
|
+
signal: controller.signal,
|
|
601
|
+
});
|
|
602
|
+
}
|
|
603
|
+
catch (err) {
|
|
604
|
+
clearTimeout(timer);
|
|
605
|
+
// Network/timeout error — retry if attempts remain, else propagate as a
|
|
606
|
+
// generic failure (fail-open, not an upgrade signal).
|
|
607
|
+
if (attempt < MAX_RETRIES) {
|
|
608
|
+
await sleep(retryDelay(attempt));
|
|
609
|
+
continue;
|
|
610
|
+
}
|
|
611
|
+
throw err;
|
|
612
|
+
}
|
|
613
|
+
clearTimeout(timer);
|
|
614
|
+
if (res.ok) {
|
|
615
|
+
const data = (await res.json());
|
|
616
|
+
return { label: data.label === "1" ? "1" : "0", confidence: data.confidence };
|
|
617
|
+
}
|
|
618
|
+
// A 403 (subscriber-only capability) can't succeed on retry — surface now.
|
|
619
|
+
if (res.status === 403)
|
|
620
|
+
throw synthesizeUpgrade(403);
|
|
621
|
+
lastStatus = res.status;
|
|
622
|
+
if (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES) {
|
|
623
|
+
await sleep(retryDelay(attempt));
|
|
624
|
+
continue;
|
|
625
|
+
}
|
|
626
|
+
break; // non-retryable status, or retries exhausted
|
|
627
|
+
}
|
|
628
|
+
// A 429 that survived every retry is sustained throttling, not a blip.
|
|
629
|
+
if (lastStatus === 429)
|
|
630
|
+
throw synthesizeUpgrade(429);
|
|
631
|
+
throw new Error(`evaluator HTTP ${lastStatus ?? "unknown"}`);
|
|
632
|
+
}
|
|
633
|
+
// --- System One decision models (batch: all policies in one call) ----------
|
|
634
|
+
// Mirrors reflexes/evaluators/systemone.py. A System One model reads the
|
|
635
|
+
// content once and decides every policy in a single forward pass, so a decision
|
|
636
|
+
// point with N policies is one request. Implemented by Zentropi cope-b-s1,
|
|
637
|
+
// TypeSafe Jev, and local self-deploys — swap with model + endpoint.
|
|
638
|
+
const SYSTEMONE_THRESHOLD = 0.5; // P(true) at/above which a policy matches ("1")
|
|
639
|
+
const SYSTEMONE_INSTRUCTION = "Does the content meet the criteria described in the following policy?\n\n";
|
|
640
|
+
const SYSTEMONE_CRITERIA = {
|
|
641
|
+
true: "The content meets the policy's criteria.",
|
|
642
|
+
false: "The content does not meet the policy's criteria.",
|
|
643
|
+
};
|
|
644
|
+
function systemOneVerdict(pTrue) {
|
|
645
|
+
const label = pTrue >= SYSTEMONE_THRESHOLD ? "1" : "0";
|
|
646
|
+
return { label, confidence: label === "1" ? pTrue : 1 - pTrue };
|
|
647
|
+
}
|
|
648
|
+
/** Batch-evaluate many policies against one content in a single /v1/systemone
|
|
649
|
+
* call. One Verdict per criteria, in order. Mirrors evaluateZentropi's retry +
|
|
650
|
+
* fail-loud-as-throw contract (the caller fails open). */
|
|
651
|
+
export async function evaluateManySystemOne(config, criteriaList, content, opts = {}) {
|
|
652
|
+
const doFetch = opts.fetchImpl ?? fetch;
|
|
653
|
+
const apiKey = process.env[config.evaluator.apiKeyEnv];
|
|
654
|
+
const questions = {};
|
|
655
|
+
criteriaList.forEach((criteria, i) => {
|
|
656
|
+
questions[`q${i}`] = {
|
|
657
|
+
type: "noul",
|
|
658
|
+
instructions: SYSTEMONE_INSTRUCTION + criteria,
|
|
659
|
+
criteria: SYSTEMONE_CRITERIA,
|
|
660
|
+
};
|
|
661
|
+
});
|
|
662
|
+
const body = JSON.stringify({
|
|
663
|
+
model: config.evaluator.model ?? "cope-b-s1",
|
|
664
|
+
questions,
|
|
665
|
+
state: { content },
|
|
666
|
+
});
|
|
667
|
+
let lastStatus;
|
|
668
|
+
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
|
|
669
|
+
const controller = new AbortController();
|
|
670
|
+
const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 30_000);
|
|
671
|
+
let res;
|
|
672
|
+
try {
|
|
673
|
+
res = await doFetch(config.evaluator.apiBase, {
|
|
674
|
+
method: "POST",
|
|
675
|
+
headers: {
|
|
676
|
+
"Content-Type": "application/json",
|
|
677
|
+
...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
|
|
678
|
+
},
|
|
679
|
+
body,
|
|
680
|
+
signal: controller.signal,
|
|
681
|
+
});
|
|
682
|
+
}
|
|
683
|
+
catch (err) {
|
|
684
|
+
clearTimeout(timer);
|
|
685
|
+
if (attempt < MAX_RETRIES) {
|
|
686
|
+
await sleep(retryDelay(attempt));
|
|
687
|
+
continue;
|
|
688
|
+
}
|
|
689
|
+
throw err;
|
|
690
|
+
}
|
|
691
|
+
clearTimeout(timer);
|
|
692
|
+
if (res.ok) {
|
|
693
|
+
const data = (await res.json());
|
|
694
|
+
const answers = data.answers ?? {};
|
|
695
|
+
return criteriaList.map((_, i) => {
|
|
696
|
+
const noul = answers[`q${i}`]?.noul;
|
|
697
|
+
if (typeof noul !== "number") {
|
|
698
|
+
throw new Error(`System One response missing noul for q${i}`);
|
|
699
|
+
}
|
|
700
|
+
return systemOneVerdict(noul);
|
|
701
|
+
});
|
|
702
|
+
}
|
|
703
|
+
if (res.status === 403)
|
|
704
|
+
throw synthesizeUpgrade(403);
|
|
705
|
+
lastStatus = res.status;
|
|
706
|
+
if (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES) {
|
|
707
|
+
await sleep(retryDelay(attempt));
|
|
708
|
+
continue;
|
|
709
|
+
}
|
|
710
|
+
break;
|
|
711
|
+
}
|
|
712
|
+
if (lastStatus === 429)
|
|
713
|
+
throw synthesizeUpgrade(429);
|
|
714
|
+
throw new Error(`systemone evaluator HTTP ${lastStatus ?? "unknown"}`);
|
|
715
|
+
}
|
|
716
|
+
async function evaluateSystemOne(config, criteria, content, opts = {}) {
|
|
717
|
+
return (await evaluateManySystemOne(config, [criteria], content, opts))[0];
|
|
718
|
+
}
|
|
719
|
+
/** Evaluate every binding against one content, returning one (Verdict | null)
|
|
720
|
+
* per binding in order (null = fail-open: policy unresolved or evaluator
|
|
721
|
+
* error). With a System One evaluator this is a SINGLE batched call; otherwise
|
|
722
|
+
* concurrent per-policy evaluate() calls — the shape the hooks used inline. */
|
|
723
|
+
async function evaluateBindings(config, bindings, content, opts) {
|
|
724
|
+
const handleEvalError = (err) => {
|
|
725
|
+
if (err instanceof UpgradeRequired) {
|
|
726
|
+
rememberUpgradeNotice(opts.sessionKey, err.userNotice);
|
|
727
|
+
opts.onFailOpenUpgrade?.(err);
|
|
728
|
+
}
|
|
729
|
+
rxwarn(`[reflexes] evaluator error (fail-open): ${String(err)}`);
|
|
730
|
+
};
|
|
731
|
+
// Resolve each binding's criteria up front; a policy that can't be resolved
|
|
732
|
+
// fails open (null) and is excluded from the batch.
|
|
733
|
+
const criteria = await Promise.all(bindings.map(async (binding) => {
|
|
734
|
+
try {
|
|
735
|
+
return await resolveBindingCriteria(binding, opts.fetchImpl);
|
|
736
|
+
}
|
|
737
|
+
catch (err) {
|
|
738
|
+
rxwarn(`[reflexes] policy "${binding.name}" unavailable, skipping (fail-open): ${String(err)}`);
|
|
739
|
+
return null;
|
|
740
|
+
}
|
|
741
|
+
}));
|
|
742
|
+
if ((config.evaluator.type ?? "systemone").toLowerCase() === "systemone") {
|
|
743
|
+
const out = bindings.map(() => null);
|
|
744
|
+
const live = criteria.map((c, i) => (c !== null ? i : -1)).filter((i) => i >= 0);
|
|
745
|
+
if (live.length === 0)
|
|
746
|
+
return out;
|
|
747
|
+
try {
|
|
748
|
+
const verdicts = await evaluateManySystemOne(config, live.map((i) => criteria[i]), content, opts);
|
|
749
|
+
live.forEach((bindingIdx, k) => {
|
|
750
|
+
out[bindingIdx] = verdicts[k] ?? null;
|
|
751
|
+
});
|
|
752
|
+
}
|
|
753
|
+
catch (err) {
|
|
754
|
+
handleEvalError(err); // whole batch fails open (all null)
|
|
755
|
+
}
|
|
756
|
+
return out;
|
|
757
|
+
}
|
|
758
|
+
// Non-System-One: concurrent per-policy evaluate (prior behavior).
|
|
759
|
+
return mapWithConcurrency(bindings, maxConcurrent(), async (binding, i) => {
|
|
760
|
+
const c = criteria[i];
|
|
761
|
+
if (c === null)
|
|
762
|
+
return null;
|
|
763
|
+
try {
|
|
764
|
+
return await evaluate(config, c, content, opts);
|
|
765
|
+
}
|
|
766
|
+
catch (err) {
|
|
767
|
+
handleEvalError(err);
|
|
768
|
+
return null;
|
|
769
|
+
}
|
|
770
|
+
});
|
|
771
|
+
}
|
|
772
|
+
// --- LLM-as-judge evaluators (openai / anthropic / gemini) -----------------
|
|
773
|
+
// Byte-for-byte mirror of the Python SYSTEM_PROMPT + `POLICY:/CONTENT:` framing
|
|
774
|
+
// (reflexes/evaluators/{openai_compatible,anthropic,gemini}.py). Unlike CoPE
|
|
775
|
+
// these are general chat models prompted to return a JSON verdict; they are
|
|
776
|
+
// slower/looser and NOT safety-calibrated the way CoPE is — offered for parity
|
|
777
|
+
// with the Python integration and self-hosted/OpenAI-compatible setups.
|
|
778
|
+
const LLM_SYSTEM_PROMPT = "You are a content classifier. You evaluate whether content matches a policy.\n\n" +
|
|
779
|
+
"You will receive a POLICY and CONTENT. Determine whether the content matches " +
|
|
780
|
+
"the policy criteria.\n\n" +
|
|
781
|
+
"Respond with ONLY a JSON object, no other text:\n" +
|
|
782
|
+
'{"label": 0 or 1, "confidence": 0.0 to 1.0}\n\n' +
|
|
783
|
+
"label=1 means the content matches the policy criteria.\n" +
|
|
784
|
+
"label=0 means it does not.";
|
|
785
|
+
function llmUserMessage(criteria, content) {
|
|
786
|
+
return `POLICY:\n${criteria}\n\nCONTENT:\n${content}`;
|
|
787
|
+
}
|
|
788
|
+
/** Thrown for a transient failure worth a retry — a retryable HTTP status or an
|
|
789
|
+
* unparseable model body. Anything else is a hard error surfaced immediately. */
|
|
790
|
+
class RetryableEvalError extends Error {
|
|
791
|
+
}
|
|
792
|
+
/** Retry wrapper for the LLM-judge backends — mirrors evaluateZentropi + the
|
|
793
|
+
* Python evaluators: retry a RetryableEvalError (transient HTTP / bad body),
|
|
794
|
+
* then fail LOUD (throw → the host fails open with a visible notice). Never
|
|
795
|
+
* returns a silent label-0. Happy path does zero retries. */
|
|
796
|
+
async function withEvalRetry(doAttempt) {
|
|
797
|
+
let last;
|
|
798
|
+
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
|
|
799
|
+
try {
|
|
800
|
+
return await doAttempt();
|
|
801
|
+
}
|
|
802
|
+
catch (err) {
|
|
803
|
+
last = err;
|
|
804
|
+
if (err instanceof RetryableEvalError && attempt < MAX_RETRIES) {
|
|
805
|
+
await sleep(retryDelay(attempt));
|
|
806
|
+
continue;
|
|
807
|
+
}
|
|
808
|
+
throw err;
|
|
809
|
+
}
|
|
810
|
+
}
|
|
811
|
+
throw last; // unreachable
|
|
812
|
+
}
|
|
813
|
+
/** Parse an LLM's JSON verdict, tolerating markdown code fences. On a parse
|
|
814
|
+
* failure, throw a RetryableEvalError (retried, then failed loud) rather than
|
|
815
|
+
* returning a silent label-0 — a silent 0 on a deny policy is a silent miss. */
|
|
816
|
+
function parseLlmVerdict(raw) {
|
|
817
|
+
let text = raw.trim();
|
|
818
|
+
if (text.startsWith("```")) {
|
|
819
|
+
const nl = text.indexOf("\n");
|
|
820
|
+
const end = text.lastIndexOf("```");
|
|
821
|
+
if (nl !== -1 && end > nl)
|
|
822
|
+
text = text.slice(nl + 1, end).trim();
|
|
823
|
+
}
|
|
824
|
+
let result;
|
|
825
|
+
try {
|
|
826
|
+
result = JSON.parse(text);
|
|
827
|
+
}
|
|
828
|
+
catch {
|
|
829
|
+
throw new RetryableEvalError(`unparseable evaluator body: ${text.slice(0, 200)}`);
|
|
830
|
+
}
|
|
831
|
+
return {
|
|
832
|
+
label: String(result.label) === "1" ? "1" : "0",
|
|
833
|
+
confidence: typeof result.confidence === "number" ? result.confidence : Number(result.confidence) || 0,
|
|
834
|
+
};
|
|
835
|
+
}
|
|
836
|
+
async function evaluateOpenAICompatible(config, criteria, content, opts = {}) {
|
|
837
|
+
const doFetch = opts.fetchImpl ?? fetch;
|
|
838
|
+
const apiKey = process.env[config.evaluator.apiKeyEnv];
|
|
839
|
+
const endpoint = config.evaluator.apiBase; // full chat/completions URL
|
|
840
|
+
const model = config.evaluator.model ?? "gpt-4o-mini";
|
|
841
|
+
const headers = {
|
|
842
|
+
"Content-Type": "application/json",
|
|
843
|
+
...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
|
|
844
|
+
};
|
|
845
|
+
const base = {
|
|
846
|
+
model,
|
|
847
|
+
messages: [
|
|
848
|
+
{ role: "system", content: LLM_SYSTEM_PROMPT },
|
|
849
|
+
{ role: "user", content: llmUserMessage(criteria, content) },
|
|
850
|
+
],
|
|
851
|
+
};
|
|
852
|
+
const post = (body) => doFetch(endpoint, { method: "POST", headers, body: JSON.stringify(body) });
|
|
853
|
+
return withEvalRetry(async () => {
|
|
854
|
+
// Widely-supported form first; newer reasoning models reject
|
|
855
|
+
// max_tokens/temperature and require max_completion_tokens (mirror Python).
|
|
856
|
+
let res = await post({ ...base, temperature: 0, max_tokens: 512 });
|
|
857
|
+
if (res.status === 400) {
|
|
858
|
+
const errText = await res.text();
|
|
859
|
+
if (errText.includes("max_completion_tokens")) {
|
|
860
|
+
res = await post({ ...base, max_completion_tokens: 512 });
|
|
861
|
+
}
|
|
862
|
+
else {
|
|
863
|
+
throw new Error(`openai evaluator HTTP 400: ${errText.slice(0, 200)}`);
|
|
864
|
+
}
|
|
865
|
+
}
|
|
866
|
+
if (RETRYABLE_STATUS.has(res.status))
|
|
867
|
+
throw new RetryableEvalError(`openai evaluator HTTP ${res.status}`);
|
|
868
|
+
if (!res.ok)
|
|
869
|
+
throw new Error(`openai evaluator HTTP ${res.status}`);
|
|
870
|
+
const data = (await res.json());
|
|
871
|
+
return parseLlmVerdict(data.choices[0].message.content);
|
|
872
|
+
});
|
|
873
|
+
}
|
|
874
|
+
async function evaluateAnthropic(config, criteria, content, opts = {}) {
|
|
875
|
+
const doFetch = opts.fetchImpl ?? fetch;
|
|
876
|
+
const apiKey = process.env[config.evaluator.apiKeyEnv];
|
|
877
|
+
const endpoint = config.evaluator.apiBase; // full /v1/messages URL
|
|
878
|
+
const model = config.evaluator.model ?? "claude-haiku-4-5-20251001";
|
|
879
|
+
return withEvalRetry(async () => {
|
|
880
|
+
const res = await doFetch(endpoint, {
|
|
881
|
+
method: "POST",
|
|
882
|
+
headers: {
|
|
883
|
+
"x-api-key": apiKey ?? "",
|
|
884
|
+
"anthropic-version": "2023-06-01",
|
|
885
|
+
"Content-Type": "application/json",
|
|
886
|
+
},
|
|
887
|
+
body: JSON.stringify({
|
|
888
|
+
model,
|
|
889
|
+
system: LLM_SYSTEM_PROMPT,
|
|
890
|
+
messages: [{ role: "user", content: llmUserMessage(criteria, content) }],
|
|
891
|
+
max_tokens: 512,
|
|
892
|
+
temperature: 0,
|
|
893
|
+
}),
|
|
894
|
+
});
|
|
895
|
+
if (RETRYABLE_STATUS.has(res.status))
|
|
896
|
+
throw new RetryableEvalError(`anthropic evaluator HTTP ${res.status}`);
|
|
897
|
+
if (!res.ok)
|
|
898
|
+
throw new Error(`anthropic evaluator HTTP ${res.status}`);
|
|
899
|
+
const data = (await res.json());
|
|
900
|
+
return parseLlmVerdict(data.content[0].text);
|
|
901
|
+
});
|
|
902
|
+
}
|
|
903
|
+
async function evaluateGemini(config, criteria, content, opts = {}) {
|
|
904
|
+
const doFetch = opts.fetchImpl ?? fetch;
|
|
905
|
+
const apiKey = process.env[config.evaluator.apiKeyEnv] ?? process.env.GOOGLE_API_KEY;
|
|
906
|
+
const model = config.evaluator.model ?? "gemini-2.5-flash";
|
|
907
|
+
// apiBase is the models base; build `{base}/{model}:generateContent` (mirror Python).
|
|
908
|
+
const endpoint = `${config.evaluator.apiBase}/${model}:generateContent?key=${apiKey ?? ""}`;
|
|
909
|
+
return withEvalRetry(async () => {
|
|
910
|
+
const res = await doFetch(endpoint, {
|
|
911
|
+
method: "POST",
|
|
912
|
+
headers: { "Content-Type": "application/json" },
|
|
913
|
+
body: JSON.stringify({
|
|
914
|
+
system_instruction: { parts: [{ text: LLM_SYSTEM_PROMPT }] },
|
|
915
|
+
contents: [{ parts: [{ text: llmUserMessage(criteria, content) }] }],
|
|
916
|
+
generationConfig: { temperature: 0, maxOutputTokens: 512 },
|
|
917
|
+
}),
|
|
918
|
+
});
|
|
919
|
+
if (RETRYABLE_STATUS.has(res.status))
|
|
920
|
+
throw new RetryableEvalError(`gemini evaluator HTTP ${res.status}`);
|
|
921
|
+
if (!res.ok)
|
|
922
|
+
throw new Error(`gemini evaluator HTTP ${res.status}`);
|
|
923
|
+
const data = (await res.json());
|
|
924
|
+
return parseLlmVerdict(data.candidates[0].content.parts[0].text);
|
|
925
|
+
});
|
|
926
|
+
}
|
|
927
|
+
export function denyReason(binding, subject = "tool call") {
|
|
928
|
+
return (`[REFLEXES POLICY CHECK] This ${subject} was blocked: it matches the ` +
|
|
929
|
+
`"${binding.name}" policy. Read the policy below and choose a compliant ` +
|
|
930
|
+
`alternative that still accomplishes the user's goal.\n\n` +
|
|
931
|
+
`Policy:\n---\n${binding.criteria}\n---`);
|
|
932
|
+
}
|
|
933
|
+
/** Self-correction instruction for a denied response (before_agent_finalize
|
|
934
|
+
* `retry.instruction`). The harness re-runs the model with this prepended. */
|
|
935
|
+
export function reviseInstruction(binding) {
|
|
936
|
+
return (`[REFLEXES POLICY CHECK] Your draft final answer matches the ` +
|
|
937
|
+
`"${binding.name}" policy and must be revised. Read the policy below and ` +
|
|
938
|
+
`rewrite your final answer to comply — without repeating completed work ` +
|
|
939
|
+
`or rerunning tools.\n\n` +
|
|
940
|
+
`Policy:\n---\n${binding.criteria}\n---`);
|
|
941
|
+
}
|
|
942
|
+
/** Default cap on concurrent evaluator calls per trigger fire. */
|
|
943
|
+
export const DEFAULT_MAX_CONCURRENT = 10;
|
|
944
|
+
function maxConcurrent() {
|
|
945
|
+
const raw = process.env.REFLEXES_MAX_CONCURRENT;
|
|
946
|
+
const n = raw ? parseInt(raw, 10) : NaN;
|
|
947
|
+
return Number.isInteger(n) && n > 0 ? n : DEFAULT_MAX_CONCURRENT;
|
|
948
|
+
}
|
|
949
|
+
/** Map over items with at most `limit` running at once; preserves order. */
|
|
950
|
+
async function mapWithConcurrency(items, limit, fn) {
|
|
951
|
+
const results = new Array(items.length);
|
|
952
|
+
let next = 0;
|
|
953
|
+
async function worker() {
|
|
954
|
+
while (next < items.length) {
|
|
955
|
+
const i = next++;
|
|
956
|
+
results[i] = await fn(items[i], i);
|
|
957
|
+
}
|
|
958
|
+
}
|
|
959
|
+
const workers = Array.from({ length: Math.min(limit, items.length) }, worker);
|
|
960
|
+
await Promise.all(workers);
|
|
961
|
+
return results;
|
|
962
|
+
}
|
|
963
|
+
/**
|
|
964
|
+
* Core hook logic, framework-agnostic and fully unit-testable.
|
|
965
|
+
* Returns undefined to allow, or a block result per OpenClaw's
|
|
966
|
+
* BeforeToolCallResult contract.
|
|
967
|
+
*/
|
|
968
|
+
export async function checkToolCall(event, config, opts = {}) {
|
|
969
|
+
if (!config)
|
|
970
|
+
return undefined;
|
|
971
|
+
const bindings = config.bindings.filter((b) => b.trigger === "before_tool_call");
|
|
972
|
+
if (bindings.length === 0)
|
|
973
|
+
return undefined;
|
|
974
|
+
// Assemble task context so policies that reason about the user's request
|
|
975
|
+
// (e.g. Unconfirmed-Destructive-Action, Constraint-Violation) get the same
|
|
976
|
+
// signal they do on other hosts. The current request + system prompt come
|
|
977
|
+
// from the llm_input carry-over (opts.taskContext); standing instructions
|
|
978
|
+
// fall back to AGENTS.md / CLAUDE.md on disk when the carry-over lacks them.
|
|
979
|
+
const currentRequest = opts.taskContext?.currentRequest ?? null;
|
|
980
|
+
const originalTask = opts.taskContext?.originalTask ?? null;
|
|
981
|
+
const standingInstructions = opts.taskContext?.standingInstructions ?? resolveStandingInstructions(opts.cwd ?? process.cwd());
|
|
982
|
+
const context = assembleTaskContext({ currentRequest, originalTask, standingInstructions }) || null;
|
|
983
|
+
const content = assembleContent(toolCallContent(event), context, "Tool call", "Task context");
|
|
984
|
+
// Log the raw tool-call payload (the security-relevant part), not the
|
|
985
|
+
// assembled string — task context is prepended there and would truncate the
|
|
986
|
+
// args out of view. `content.length` still reports the full assembled size.
|
|
987
|
+
rxdebug(`before_tool_call: evaluating ${event.toolName} (${content.length} chars assembled): ${_truncForLog(toolCallContent(event))}`);
|
|
988
|
+
// Evaluate all bound policies in parallel (cap: REFLEXES_MAX_CONCURRENT,
|
|
989
|
+
// default 10), then apply results in binding order — first deny wins.
|
|
990
|
+
const verdicts = await evaluateBindings(config, bindings, content, opts);
|
|
991
|
+
for (let i = 0; i < bindings.length; i++) {
|
|
992
|
+
const binding = bindings[i];
|
|
993
|
+
const verdict = verdicts[i];
|
|
994
|
+
rxdebug(`before_tool_call: policy ${binding.name} → label=${verdict?.label ?? "null"}` +
|
|
995
|
+
(verdict?.confidence !== undefined ? ` confidence=${verdict.confidence}` : ""));
|
|
996
|
+
if (!verdict || verdict.label !== "1")
|
|
997
|
+
continue;
|
|
998
|
+
if (binding.action === "deny") {
|
|
999
|
+
return { block: true, blockReason: denyReason(binding) };
|
|
1000
|
+
}
|
|
1001
|
+
// flag / log: surface without blocking.
|
|
1002
|
+
rxwarn(`[reflexes] ${binding.action}: tool call ${event.toolName} matched policy ${binding.name}` +
|
|
1003
|
+
(verdict.confidence !== undefined ? ` (confidence ${verdict.confidence})` : ""));
|
|
1004
|
+
if (binding.action === "flag")
|
|
1005
|
+
opts.onFlag?.(flagNote(binding, verdict, "tool call"));
|
|
1006
|
+
}
|
|
1007
|
+
return undefined;
|
|
1008
|
+
}
|
|
1009
|
+
/**
|
|
1010
|
+
* Core `before_response` logic: evaluate the agent's final reply against the
|
|
1011
|
+
* bound `before_response` policies. On deny, return `{ action: "revise" }` so
|
|
1012
|
+
* OpenClaw blocks finalization and re-runs the model with the policy text as
|
|
1013
|
+
* the revision instruction (the before_agent_finalize self-correct loop).
|
|
1014
|
+
*/
|
|
1015
|
+
export async function checkResponse(event, config, opts = {}) {
|
|
1016
|
+
if (!config)
|
|
1017
|
+
return undefined;
|
|
1018
|
+
const bindings = config.bindings.filter((b) => b.trigger === "before_response");
|
|
1019
|
+
if (bindings.length === 0)
|
|
1020
|
+
return undefined;
|
|
1021
|
+
const response = event.lastAssistantMessage;
|
|
1022
|
+
if (typeof response !== "string" || !response.trim())
|
|
1023
|
+
return undefined; // nothing to evaluate
|
|
1024
|
+
const currentRequest = opts.taskContext?.currentRequest ?? null;
|
|
1025
|
+
const originalTask = opts.taskContext?.originalTask ?? null;
|
|
1026
|
+
const standingInstructions = opts.taskContext?.standingInstructions ?? resolveStandingInstructions(opts.cwd ?? process.cwd());
|
|
1027
|
+
// Append the trajectory ("Actions this turn:") after the task context, as
|
|
1028
|
+
// supporting context for what the response claims to have done.
|
|
1029
|
+
const context = [assembleTaskContext({ currentRequest, originalTask, standingInstructions }), opts.trajectory]
|
|
1030
|
+
.filter((s) => Boolean(s && s.trim()))
|
|
1031
|
+
.join("\n\n") || null;
|
|
1032
|
+
const content = assembleContent(response, context, "Agent response", "Task context");
|
|
1033
|
+
// Log the raw response (the evaluated payload), not the context-prefixed
|
|
1034
|
+
// assembled string, so it isn't truncated away by long task context.
|
|
1035
|
+
rxdebug(`before_response: evaluating response (${content.length} chars assembled): ${_truncForLog(response)}`);
|
|
1036
|
+
const verdicts = await evaluateBindings(config, bindings, content, opts);
|
|
1037
|
+
for (let i = 0; i < bindings.length; i++) {
|
|
1038
|
+
const binding = bindings[i];
|
|
1039
|
+
const verdict = verdicts[i];
|
|
1040
|
+
rxdebug(`before_response: policy ${binding.name} → label=${verdict?.label ?? "null"}` +
|
|
1041
|
+
(verdict?.confidence !== undefined ? ` confidence=${verdict.confidence}` : ""));
|
|
1042
|
+
if (!verdict || verdict.label !== "1")
|
|
1043
|
+
continue;
|
|
1044
|
+
if (binding.action === "deny") {
|
|
1045
|
+
return {
|
|
1046
|
+
action: "revise",
|
|
1047
|
+
reason: `reflexes: ${binding.name}`,
|
|
1048
|
+
retry: { instruction: reviseInstruction(binding) },
|
|
1049
|
+
};
|
|
1050
|
+
}
|
|
1051
|
+
// flag / log: surface without blocking (return nothing = accept finalize).
|
|
1052
|
+
rxwarn(`[reflexes] ${binding.action}: response matched policy ${binding.name}` +
|
|
1053
|
+
(verdict.confidence !== undefined ? ` (confidence ${verdict.confidence})` : ""));
|
|
1054
|
+
if (binding.action === "flag")
|
|
1055
|
+
opts.onFlag?.(flagNote(binding, verdict, "response"));
|
|
1056
|
+
}
|
|
1057
|
+
return undefined;
|
|
1058
|
+
}
|
|
1059
|
+
/**
|
|
1060
|
+
* Core `on_input` logic: evaluate the user's prompt against the bound `on_input`
|
|
1061
|
+
* policies BEFORE it reaches the model, via OpenClaw's `before_agent_run` gate.
|
|
1062
|
+
* On deny, return `{ outcome: "block" }` so OpenClaw never submits the prompt.
|
|
1063
|
+
*
|
|
1064
|
+
* `before_agent_run` is FAIL-CLOSED in OpenClaw (a void/thrown result blocks the
|
|
1065
|
+
* prompt), so this ALWAYS returns an explicit decision and swallows every
|
|
1066
|
+
* internal error into `{ outcome: "pass" }` — Reflexes fails OPEN, never blocking
|
|
1067
|
+
* a user because our own check broke.
|
|
1068
|
+
*/
|
|
1069
|
+
export async function checkInput(event, config, opts = {}) {
|
|
1070
|
+
try {
|
|
1071
|
+
if (!config)
|
|
1072
|
+
return { outcome: "pass" };
|
|
1073
|
+
const bindings = config.bindings.filter((b) => b.trigger === "on_input");
|
|
1074
|
+
if (bindings.length === 0)
|
|
1075
|
+
return { outcome: "pass" };
|
|
1076
|
+
const content = typeof event.prompt === "string" ? event.prompt : "";
|
|
1077
|
+
if (!content.trim())
|
|
1078
|
+
return { outcome: "pass" };
|
|
1079
|
+
rxdebug(`on_input: evaluating prompt (${content.length} chars): ${_truncForLog(content)}`);
|
|
1080
|
+
// on_input: the content IS the request — no extra task context to assemble.
|
|
1081
|
+
const verdicts = await evaluateBindings(config, bindings, content, opts);
|
|
1082
|
+
for (let i = 0; i < bindings.length; i++) {
|
|
1083
|
+
const binding = bindings[i];
|
|
1084
|
+
const verdict = verdicts[i];
|
|
1085
|
+
rxdebug(`on_input: policy ${binding.name} → label=${verdict?.label ?? "null"}` +
|
|
1086
|
+
(verdict?.confidence !== undefined ? ` confidence=${verdict.confidence}` : ""));
|
|
1087
|
+
if (!verdict || verdict.label !== "1")
|
|
1088
|
+
continue;
|
|
1089
|
+
if (binding.action === "deny") {
|
|
1090
|
+
// Block the prompt before the model runs. `reason` is internal; `message`
|
|
1091
|
+
// is the user-facing detail (the policy feedback the agent self-corrects on).
|
|
1092
|
+
return { outcome: "block", reason: `reflexes: ${binding.name}`, message: denyReason(binding, "request") };
|
|
1093
|
+
}
|
|
1094
|
+
// flag / log: surface without blocking.
|
|
1095
|
+
rxwarn(`[reflexes] ${binding.action}: input matched policy ${binding.name}` +
|
|
1096
|
+
(verdict.confidence !== undefined ? ` (confidence ${verdict.confidence})` : ""));
|
|
1097
|
+
if (binding.action === "flag")
|
|
1098
|
+
opts.onFlag?.(flagNote(binding, verdict, "input"));
|
|
1099
|
+
}
|
|
1100
|
+
return { outcome: "pass" };
|
|
1101
|
+
}
|
|
1102
|
+
catch (err) {
|
|
1103
|
+
// Never throw — a thrown/void return is fail-CLOSED (blocks the prompt).
|
|
1104
|
+
rxwarn(`[reflexes] on_input check failed (fail-open): ${String(err)}`);
|
|
1105
|
+
return { outcome: "pass" };
|
|
1106
|
+
}
|
|
1107
|
+
}
|
|
1108
|
+
/** OpenClaw plugin entry. Config is loaded once at registration. Capture hooks
|
|
1109
|
+
* (`llm_input`, `message_received`, `session_end`, `after_tool_call`) build the
|
|
1110
|
+
* task context + trajectory; `before_agent_run` (on_input), `before_tool_call`,
|
|
1111
|
+
* and `before_agent_finalize` (before_response) enforce policies;
|
|
1112
|
+
* `reply_payload_sending` adds a fail-open upgrade notice as
|
|
1113
|
+
* a distinct footer block so the user sees when enforcement was degraded (the
|
|
1114
|
+
* agent is also informed directly via a next-turn injection). */
|
|
1115
|
+
const entry = {
|
|
1116
|
+
id: "reflexes",
|
|
1117
|
+
name: "Reflexes",
|
|
1118
|
+
description: "An open safety harness for AI agents — plain-English policy checks on tool calls and replies.",
|
|
1119
|
+
register(api) {
|
|
1120
|
+
const config = loadConfig(process.env.REFLEXES_CONFIG);
|
|
1121
|
+
if (!config) {
|
|
1122
|
+
rxwarn("[reflexes] no reflexes.yaml found (~/.reflexes/reflexes.yaml or ./reflexes.yaml); plugin idle");
|
|
1123
|
+
}
|
|
1124
|
+
// Capture the current request + system prompt each model call (same run).
|
|
1125
|
+
api.on("llm_input", (event) => rememberRequest(api, event), { priority: 100 });
|
|
1126
|
+
// Remember the session's first message (Original task); drop it on end.
|
|
1127
|
+
api.on("message_received", (event) => rememberOriginalTask(event), { priority: 100 });
|
|
1128
|
+
api.on("session_end", (event) => forgetSession(event), { priority: 100 });
|
|
1129
|
+
// Accumulate the per-run trajectory (what the agent actually did).
|
|
1130
|
+
api.on("after_tool_call", (event, ctx) => rememberAction(api, event, ctx), { priority: 100 });
|
|
1131
|
+
// Surface a fail-open upgrade notice as a distinct context/footer block on
|
|
1132
|
+
// the reply the user sees — OpenClaw's context/prompt channels are
|
|
1133
|
+
// model-facing only, so the outbound reply is the only reliable way to tell
|
|
1134
|
+
// the human enforcement was degraded. Never mutates the model's response.
|
|
1135
|
+
api.on("reply_payload_sending", (event, ctx) => appendUpgradeNotice(event, ctx), { priority: 100 });
|
|
1136
|
+
// Enforce on_input policies via the input gate — a deny blocks the prompt
|
|
1137
|
+
// before the model runs. (Conversation hook: needs allowConversationAccess.)
|
|
1138
|
+
api.on("before_agent_run", async (event, ctx) => checkInput(event, config, {
|
|
1139
|
+
sessionKey: ctx.sessionKey,
|
|
1140
|
+
onFailOpenUpgrade: (upgrade) => enqueueAgentNotice(api, ctx.sessionKey, upgrade),
|
|
1141
|
+
onFlag: (note) => enqueueAgentText(api, ctx.sessionKey, note, `reflexes-flag:${ctx.sessionKey}`),
|
|
1142
|
+
}), { priority: 100 });
|
|
1143
|
+
// Enforce before_tool_call policies on each tool call.
|
|
1144
|
+
api.on("before_tool_call", async (event, ctx) => checkToolCall(event, config, {
|
|
1145
|
+
taskContext: recallTaskContext(api, ctx),
|
|
1146
|
+
sessionKey: ctx.sessionKey,
|
|
1147
|
+
onFailOpenUpgrade: (upgrade) => enqueueAgentNotice(api, ctx.sessionKey, upgrade),
|
|
1148
|
+
onFlag: (note) => enqueueAgentText(api, ctx.sessionKey, note, `reflexes-flag:${ctx.sessionKey}`),
|
|
1149
|
+
}), { priority: 100 });
|
|
1150
|
+
// Enforce before_response policies on the agent's final reply, with the
|
|
1151
|
+
// trajectory so completion policies can check claims against what happened.
|
|
1152
|
+
api.on("before_agent_finalize", async (event, ctx) => checkResponse(event, config, {
|
|
1153
|
+
taskContext: recallTaskContext(api, ctx),
|
|
1154
|
+
trajectory: recallTrajectory(api, ctx),
|
|
1155
|
+
sessionKey: ctx.sessionKey,
|
|
1156
|
+
onFailOpenUpgrade: (upgrade) => enqueueAgentNotice(api, ctx.sessionKey, upgrade),
|
|
1157
|
+
onFlag: (note) => enqueueAgentText(api, ctx.sessionKey, note, `reflexes-flag:${ctx.sessionKey}`),
|
|
1158
|
+
}), { priority: 100 });
|
|
1159
|
+
},
|
|
1160
|
+
};
|
|
1161
|
+
export default entry;
|