@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/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;