@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/README.md
CHANGED
|
@@ -1,3 +1,128 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @zentropi/reflexes-openclaw
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**An open safety harness for OpenClaw agents.** Plain-English Reflexes policies
|
|
4
|
+
are checked on each tool call and each reply by a policy-steerable classifier
|
|
5
|
+
(CoPE by default, ~200ms). On a policy match the agent gets the policy text back
|
|
6
|
+
and self-corrects — a blocked tool call is retried, a non-compliant reply is
|
|
7
|
+
revised.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
The simplest install is agent-driven: ask your agent to *"Install the Reflexes skill from github.com/zentropi-ai/reflexes — clone the repo, then read and follow skill/SKILL.md to wire it into this agent."* — it follows the canonical procedure in the top-level
|
|
12
|
+
[`SKILL.md`](../../skill/SKILL.md) and does everything below for you. To install
|
|
13
|
+
by hand:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
openclaw plugins install @zentropi/reflexes-openclaw # or a local path
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
**Grant conversation access (required):**
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
openclaw config set plugins.entries.reflexes.hooks.allowConversationAccess true
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Without this, tool-call policies still fire but with no `Current request`
|
|
26
|
+
context, and reply policies don't enforce — OpenClaw blocks those hooks for
|
|
27
|
+
third-party plugins by default.
|
|
28
|
+
|
|
29
|
+
## Configure
|
|
30
|
+
|
|
31
|
+
Create `~/.reflexes/reflexes.yaml` — the same config every Reflexes host shares —
|
|
32
|
+
and bind policies to triggers:
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
reflexes:
|
|
36
|
+
default:
|
|
37
|
+
- policy: ./policies/Unconfirmed-Destructive-Action.md
|
|
38
|
+
name: Unconfirmed-Destructive-Action
|
|
39
|
+
trigger: before_tool_call
|
|
40
|
+
action: deny
|
|
41
|
+
- policy: ./policies/Sycophancy.md
|
|
42
|
+
name: Sycophancy
|
|
43
|
+
trigger: before_response
|
|
44
|
+
action: deny
|
|
45
|
+
evaluators:
|
|
46
|
+
default:
|
|
47
|
+
type: systemone
|
|
48
|
+
model: cope-b-s1
|
|
49
|
+
endpoint: https://api.zentropi.ai/v1/systemone
|
|
50
|
+
api_key_env: ZENTROPI_API_KEY
|
|
51
|
+
|
|
52
|
+
# --- Operational settings (optional; safe defaults) ---
|
|
53
|
+
enabled: true # global on/off; false disables ALL enforcement. Absent = enabled.
|
|
54
|
+
logging:
|
|
55
|
+
level: warning # off | error | warning (default) | info | debug — content ONLY ever at debug
|
|
56
|
+
format: text # text | json
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Set `ZENTROPI_API_KEY` in the gateway environment and restart the gateway.
|
|
60
|
+
|
|
61
|
+
**Where the policy files come from.** The `./policies/*.md` files are *not*
|
|
62
|
+
bundled with the npm plugin — they're the shared Reflexes starter set. The
|
|
63
|
+
agent-driven install above places them in `~/.reflexes/policies/` for you. If
|
|
64
|
+
you wire OpenClaw by hand, either copy the starter set from
|
|
65
|
+
[`skill/reflexes/_starter_policies/`](../../skill/reflexes/_starter_policies)
|
|
66
|
+
into `~/.reflexes/policies/`, write your own (see
|
|
67
|
+
[`SKILL.md`](../../skill/SKILL.md)), or skip local files entirely and point
|
|
68
|
+
`policy:` at a hosted reference (next).
|
|
69
|
+
|
|
70
|
+
**Policy sources.** `policy:` can be a local file (preferred), a Zentropi-hosted
|
|
71
|
+
labeler (`zentropi:<labeler_id>[@<version>]`), or a GitHub-hosted file
|
|
72
|
+
(`github:<owner>/<repo>/<path>@<tag-or-sha>`). Hosted policies are fetched and
|
|
73
|
+
cached on first use.
|
|
74
|
+
|
|
75
|
+
**Evaluator backends.** `type` can be `systemone` (the default — a System One
|
|
76
|
+
decision model, Zentropi `cope-b-s1` served over `/v1/systemone`, which
|
|
77
|
+
evaluates **all policies at a decision point in one call**; also TypeSafe
|
|
78
|
+
`jev-latest` or a local one), `zentropi` (CoPE single-label `/v1/label`),
|
|
79
|
+
`openai`, `anthropic`, or `gemini`. The LLM backends are general
|
|
80
|
+
chat models prompted to classify, so they are looser and less calibrated than
|
|
81
|
+
CoPE; for them, set `model`, `api_key_env`, and (if needed) `endpoint`.
|
|
82
|
+
|
|
83
|
+
## What it does
|
|
84
|
+
|
|
85
|
+
Reflexes enforces at three points in the agent loop:
|
|
86
|
+
|
|
87
|
+
- **`on_input`** — the user's prompt is checked before it reaches the model (via
|
|
88
|
+
OpenClaw's `before_agent_run` input gate). On a deny the prompt is blocked and
|
|
89
|
+
never submitted. (Conversation hook — requires `allowConversationAccess`.)
|
|
90
|
+
- **`before_tool_call`** — every tool call is checked before it runs. On a deny
|
|
91
|
+
the call is blocked and the policy text is handed back as the tool error, so
|
|
92
|
+
the agent sees why and chooses a compliant alternative.
|
|
93
|
+
- **`before_response`** — the agent's final reply is checked before delivery. On
|
|
94
|
+
a deny the reply goes back for revision with the policy as the instruction, and
|
|
95
|
+
the agent rewrites it (bounded by OpenClaw's max revisions).
|
|
96
|
+
|
|
97
|
+
`flag` and `log` record a match without blocking.
|
|
98
|
+
|
|
99
|
+
Every check receives the same **task context** as the other Reflexes hosts, so a
|
|
100
|
+
policy classifies the same way here as on Claude Code: the user's current
|
|
101
|
+
request, the session's original task, standing instructions (system prompt or
|
|
102
|
+
`AGENTS.md`), and — for reply policies — what the agent actually did this turn.
|
|
103
|
+
|
|
104
|
+
**Fail-open.** If the evaluator can't be reached, the check fails open (the
|
|
105
|
+
operation proceeds) and a one-line notice is surfaced two ways: appended to the
|
|
106
|
+
reply the user sees (never altering the model's own text) and given to the agent
|
|
107
|
+
on its next turn, so degraded enforcement is never silent. A sustained rate limit
|
|
108
|
+
or subscriber-only response adds a pointer to self-hosting the open CoPE model.
|
|
109
|
+
|
|
110
|
+
## Limitations
|
|
111
|
+
|
|
112
|
+
- **The enforcing triggers are `on_input`, `before_tool_call`, and
|
|
113
|
+
`before_response`.** `after_tool_call` can't enforce on OpenClaw — its post-tool
|
|
114
|
+
hook is observe-only (return discarded) and fires after the tool has already
|
|
115
|
+
run, so bindings on it load but don't enforce. This is an OpenClaw limitation,
|
|
116
|
+
not a Reflexes one. (`on_input` enforcement uses the `before_agent_run` gate,
|
|
117
|
+
which is a conversation hook — set `allowConversationAccess: true`.)
|
|
118
|
+
- Policies load once at gateway startup; restart after editing `reflexes.yaml`.
|
|
119
|
+
- The user-facing fail-open notice rides the outbound reply, so it appears only
|
|
120
|
+
when a chat channel is configured (Discord, Slack, …). With `openclaw agent
|
|
121
|
+
--local` and no channel it isn't shown — but the agent is still notified and
|
|
122
|
+
the check still fails open with a log, so nothing is lost silently.
|
|
123
|
+
|
|
124
|
+
## About
|
|
125
|
+
|
|
126
|
+
Part of [Reflexes](https://github.com/zentropi-ai/reflexes) — an open safety
|
|
127
|
+
harness for AI agents. Tested against OpenClaw 2026.6.11–2026.7.1. Licensed
|
|
128
|
+
under Apache-2.0.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
import { type PolicyRef } from "./policy.js";
|
|
2
|
+
export { parseRef, resolveCriteria, stripFrontmatter, PolicyNotFound, _internal as policyInternal } from "./policy.js";
|
|
3
|
+
export type { PolicyRef } from "./policy.js";
|
|
4
|
+
export type ReflexAction = "deny" | "flag" | "log";
|
|
5
|
+
export interface ReflexBinding {
|
|
6
|
+
policy: string;
|
|
7
|
+
trigger: string;
|
|
8
|
+
action: ReflexAction;
|
|
9
|
+
criteria: string;
|
|
10
|
+
name: string;
|
|
11
|
+
ref: PolicyRef;
|
|
12
|
+
baseDir?: string;
|
|
13
|
+
}
|
|
14
|
+
export interface ReflexesConfig {
|
|
15
|
+
bindings: ReflexBinding[];
|
|
16
|
+
evaluator: {
|
|
17
|
+
type: string;
|
|
18
|
+
model?: string;
|
|
19
|
+
apiBase: string;
|
|
20
|
+
apiKeyEnv: string;
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
export interface BeforeToolCallEvent {
|
|
24
|
+
toolName: string;
|
|
25
|
+
params: Record<string, unknown>;
|
|
26
|
+
toolCallId?: string;
|
|
27
|
+
runId?: string;
|
|
28
|
+
derivedPaths?: readonly string[];
|
|
29
|
+
}
|
|
30
|
+
export interface BeforeToolCallResult {
|
|
31
|
+
block?: boolean;
|
|
32
|
+
blockReason?: string;
|
|
33
|
+
}
|
|
34
|
+
export interface BeforeAgentRunEvent {
|
|
35
|
+
prompt?: string;
|
|
36
|
+
}
|
|
37
|
+
export type InputGateDecision = {
|
|
38
|
+
outcome: "pass";
|
|
39
|
+
} | {
|
|
40
|
+
outcome: "block";
|
|
41
|
+
reason: string;
|
|
42
|
+
message?: string;
|
|
43
|
+
};
|
|
44
|
+
export interface Verdict {
|
|
45
|
+
label: "0" | "1";
|
|
46
|
+
confidence?: number;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* A policy IS its criteria: the whole document is sent to the evaluator. A
|
|
50
|
+
* leading YAML frontmatter block, if present, is optional metadata and is
|
|
51
|
+
* stripped. Mirrors reflexes.document.parse (SPEC §3).
|
|
52
|
+
*/
|
|
53
|
+
export declare function extractCriteria(markdown: string): string;
|
|
54
|
+
export declare function loadConfig(configPath?: string): ReflexesConfig | null;
|
|
55
|
+
/** Resolve a binding's criteria on demand, memoizing the result. File refs are
|
|
56
|
+
* already resolved at load; hosted refs (zentropi:/github:) fetch + cache on
|
|
57
|
+
* first use, then reuse the cached value (so denyReason/reviseInstruction, which
|
|
58
|
+
* read binding.criteria, see the resolved text). */
|
|
59
|
+
export declare function resolveBindingCriteria(binding: ReflexBinding, fetchImpl?: typeof fetch): Promise<string>;
|
|
60
|
+
/** Serialize the pending tool call as the SPEC §5 JSON shape — matches the
|
|
61
|
+
* Python reference and every other host: `{"tool_name": ..., "args": ...}`. */
|
|
62
|
+
export declare function toolCallContent(event: BeforeToolCallEvent): string;
|
|
63
|
+
export interface TaskContextSources {
|
|
64
|
+
currentRequest?: string | null;
|
|
65
|
+
originalTask?: string | null;
|
|
66
|
+
standingInstructions?: string | null;
|
|
67
|
+
}
|
|
68
|
+
/** Assemble the labeled task-context block (SPEC §5.1); "" if nothing given.
|
|
69
|
+
* Mirrors reflexes._context.assemble_task_context. */
|
|
70
|
+
export declare function assembleTaskContext(src: TaskContextSources): string;
|
|
71
|
+
/** Frame content + context for the evaluator. Mirrors
|
|
72
|
+
* reflexes.core._assemble_content byte-for-byte. */
|
|
73
|
+
export declare function assembleContent(content: string, context: string | null, checkType?: string, contextLabel?: string): string;
|
|
74
|
+
/** Subset of OpenClaw's `PluginHookLlmInputEvent` we read. */
|
|
75
|
+
export interface LlmInputEvent {
|
|
76
|
+
runId: string;
|
|
77
|
+
prompt: string;
|
|
78
|
+
systemPrompt?: string;
|
|
79
|
+
}
|
|
80
|
+
/** Subset of OpenClaw's `PluginHookToolContext` (`before_tool_call` ctx arg). */
|
|
81
|
+
export interface ToolContext {
|
|
82
|
+
runId?: string;
|
|
83
|
+
sessionKey?: string;
|
|
84
|
+
sessionId?: string;
|
|
85
|
+
}
|
|
86
|
+
/** Subset of OpenClaw's `PluginHookMessageReceivedEvent` — an inbound message.
|
|
87
|
+
* The first per session is the "Original task". */
|
|
88
|
+
export interface MessageReceivedEvent {
|
|
89
|
+
from?: string;
|
|
90
|
+
content: string;
|
|
91
|
+
sessionKey?: string;
|
|
92
|
+
runId?: string;
|
|
93
|
+
}
|
|
94
|
+
/** Subset of OpenClaw's `PluginHookSessionEndEvent` (for original-task cleanup). */
|
|
95
|
+
export interface SessionEndEvent {
|
|
96
|
+
sessionKey?: string;
|
|
97
|
+
sessionId?: string;
|
|
98
|
+
}
|
|
99
|
+
/** Subset of OpenClaw's `PluginHookAfterToolCallEvent` (a completed tool call,
|
|
100
|
+
* observe-only). Used to accumulate the per-run trajectory. */
|
|
101
|
+
export interface AfterToolCallEvent {
|
|
102
|
+
toolName: string;
|
|
103
|
+
params?: Record<string, unknown>;
|
|
104
|
+
runId?: string;
|
|
105
|
+
result?: unknown;
|
|
106
|
+
error?: string;
|
|
107
|
+
}
|
|
108
|
+
/** Subset of OpenClaw's `PluginHookBeforeAgentFinalizeEvent` (the Stop-hook
|
|
109
|
+
* analog — carries the agent's final reply). */
|
|
110
|
+
export interface FinalizeEvent {
|
|
111
|
+
runId?: string;
|
|
112
|
+
sessionId?: string;
|
|
113
|
+
lastAssistantMessage?: string;
|
|
114
|
+
stopHookActive?: boolean;
|
|
115
|
+
}
|
|
116
|
+
/** OpenClaw's `PluginHookBeforeAgentFinalizeResult`. `action: "revise"` blocks
|
|
117
|
+
* finalization and re-runs the model with `retry.instruction` (self-correct). */
|
|
118
|
+
export interface FinalizeResult {
|
|
119
|
+
action?: "continue" | "revise" | "finalize";
|
|
120
|
+
reason?: string;
|
|
121
|
+
retry?: {
|
|
122
|
+
instruction: string;
|
|
123
|
+
maxAttempts?: number;
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
/** Subset of OpenClaw's `PluginHookMessageContext` (outbound). `sessionKey` is
|
|
127
|
+
* the same canonical value the tool/finalize hooks fire with, so it correlates
|
|
128
|
+
* to the run that produced this reply. Omitted when no session is resolvable. */
|
|
129
|
+
export interface MessageContext {
|
|
130
|
+
sessionKey?: string;
|
|
131
|
+
}
|
|
132
|
+
/** OpenClaw's `MessagePresentationBlock` — the structured reply block types we
|
|
133
|
+
* touch. Other block types (buttons, select, divider) pass through unchanged
|
|
134
|
+
* via the index signature. `context` is "small context/footer text"; `text`
|
|
135
|
+
* is a normal paragraph (see message-presentation.md). */
|
|
136
|
+
export type PresentationBlock = {
|
|
137
|
+
type: "text";
|
|
138
|
+
text: string;
|
|
139
|
+
} | {
|
|
140
|
+
type: "context";
|
|
141
|
+
text: string;
|
|
142
|
+
} | {
|
|
143
|
+
type: string;
|
|
144
|
+
[key: string]: unknown;
|
|
145
|
+
};
|
|
146
|
+
/** OpenClaw's `MessagePresentation` — a structured reply. `blocks` is required;
|
|
147
|
+
* `title`/`tone` are optional and left untouched when present. */
|
|
148
|
+
export interface ReplyPresentation {
|
|
149
|
+
title?: string;
|
|
150
|
+
tone?: string;
|
|
151
|
+
blocks: PresentationBlock[];
|
|
152
|
+
[key: string]: unknown;
|
|
153
|
+
}
|
|
154
|
+
/** Subset of OpenClaw's `PluginHookReplyPayload` (`Omit<ReplyPayload,
|
|
155
|
+
* "trustedLocalMedia">`). We read `text` + `presentation`; every other field
|
|
156
|
+
* (mediaUrls, channelData, replyToId, …) is preserved verbatim via the index
|
|
157
|
+
* signature. */
|
|
158
|
+
export interface ReplyPayload {
|
|
159
|
+
text?: string;
|
|
160
|
+
presentation?: ReplyPresentation;
|
|
161
|
+
[key: string]: unknown;
|
|
162
|
+
}
|
|
163
|
+
/** Subset of OpenClaw's `PluginHookReplyPayloadSendingEvent`. */
|
|
164
|
+
export interface ReplyPayloadSendingEvent {
|
|
165
|
+
payload: ReplyPayload;
|
|
166
|
+
sessionKey?: string;
|
|
167
|
+
}
|
|
168
|
+
/** OpenClaw's `PluginHookReplyPayloadSendingResult`. Returning `payload`
|
|
169
|
+
* replaces the outbound payload; returning nothing leaves it untouched. */
|
|
170
|
+
export interface ReplyPayloadSendingResult {
|
|
171
|
+
payload?: ReplyPayload;
|
|
172
|
+
}
|
|
173
|
+
interface RunContextApi {
|
|
174
|
+
setRunContext(patch: {
|
|
175
|
+
runId: string;
|
|
176
|
+
namespace: string;
|
|
177
|
+
value?: unknown;
|
|
178
|
+
unset?: boolean;
|
|
179
|
+
}): boolean;
|
|
180
|
+
getRunContext(params: {
|
|
181
|
+
runId: string;
|
|
182
|
+
namespace: string;
|
|
183
|
+
}): unknown;
|
|
184
|
+
}
|
|
185
|
+
/** Subset of OpenClaw's `PluginNextTurnInjection` — durable context that reaches
|
|
186
|
+
* the model on its next turn exactly once (deduped by idempotencyKey). */
|
|
187
|
+
interface NextTurnInjection {
|
|
188
|
+
sessionKey: string;
|
|
189
|
+
text: string;
|
|
190
|
+
idempotencyKey?: string;
|
|
191
|
+
}
|
|
192
|
+
/** Subset of `api.session.workflow` — the sanctioned seam for a policy summary
|
|
193
|
+
* to reach the next model turn. Optional so older gateways / test mocks
|
|
194
|
+
* without it degrade gracefully (guarded at the call site). */
|
|
195
|
+
interface SessionApi {
|
|
196
|
+
workflow?: {
|
|
197
|
+
enqueueNextTurnInjection(injection: NextTurnInjection): Promise<unknown> | unknown;
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
interface HookOpts {
|
|
201
|
+
priority?: number;
|
|
202
|
+
timeoutMs?: number;
|
|
203
|
+
}
|
|
204
|
+
/** Subset of OpenClaw's `OpenClawPluginApi` the plugin uses. */
|
|
205
|
+
export interface OpenClawPluginApi {
|
|
206
|
+
on(hook: "llm_input", handler: (event: LlmInputEvent, ctx: ToolContext) => void, opts?: HookOpts): void;
|
|
207
|
+
on(hook: "message_received", handler: (event: MessageReceivedEvent, ctx: ToolContext) => void, opts?: HookOpts): void;
|
|
208
|
+
on(hook: "session_end", handler: (event: SessionEndEvent, ctx: ToolContext) => void, opts?: HookOpts): void;
|
|
209
|
+
on(hook: "after_tool_call", handler: (event: AfterToolCallEvent, ctx: ToolContext) => void, opts?: HookOpts): void;
|
|
210
|
+
on(hook: "before_agent_run", handler: (event: BeforeAgentRunEvent, ctx: ToolContext) => Promise<InputGateDecision> | InputGateDecision, opts?: HookOpts): void;
|
|
211
|
+
on(hook: "reply_payload_sending", handler: (event: ReplyPayloadSendingEvent, ctx: MessageContext) => ReplyPayloadSendingResult | undefined, opts?: HookOpts): void;
|
|
212
|
+
on(hook: "before_tool_call", handler: (event: BeforeToolCallEvent, ctx: ToolContext) => Promise<BeforeToolCallResult | undefined> | BeforeToolCallResult | undefined, opts?: HookOpts): void;
|
|
213
|
+
on(hook: "before_agent_finalize", handler: (event: FinalizeEvent, ctx: ToolContext) => Promise<FinalizeResult | undefined> | FinalizeResult | undefined, opts?: HookOpts): void;
|
|
214
|
+
runContext: RunContextApi;
|
|
215
|
+
session?: SessionApi;
|
|
216
|
+
}
|
|
217
|
+
/** Capture hook: stash this run's request + system prompt (best-effort). */
|
|
218
|
+
export declare function rememberRequest(api: OpenClawPluginApi, event: LlmInputEvent): void;
|
|
219
|
+
/** Capture hook: remember the first inbound message of a session. */
|
|
220
|
+
export declare function rememberOriginalTask(event: MessageReceivedEvent): void;
|
|
221
|
+
/** Record a fail-open upgrade notice for this session (first one wins — once
|
|
222
|
+
* per session). No-op without a sessionKey (nothing to correlate on). */
|
|
223
|
+
export declare function rememberUpgradeNotice(sessionKey: string | undefined, notice: string): void;
|
|
224
|
+
/** Return this session's pending notice the first time it's read, then mark it
|
|
225
|
+
* surfaced so it lands on exactly one reply. */
|
|
226
|
+
export declare function takeUpgradeNotice(sessionKey: string | undefined): string | null;
|
|
227
|
+
/** Inject the fail-open upgrade notice into the model's NEXT turn, so the agent
|
|
228
|
+
* itself learns enforcement was degraded — independent of any outbound channel
|
|
229
|
+
* (unlike the user-facing reply footer). Uses OpenClaw's next-turn-injection
|
|
230
|
+
* seam, deduped once per session by idempotencyKey. Fire-and-forget and fully
|
|
231
|
+
* guarded: an injection failure (or a gateway without the API) must never
|
|
232
|
+
* break the agent loop. */
|
|
233
|
+
/** Enqueue model-visible text for the next turn (OpenClaw's integrity-safe
|
|
234
|
+
* agent channel — never touches the current reply). Advisory; never throws. */
|
|
235
|
+
export declare function enqueueAgentText(api: OpenClawPluginApi, sessionKey: string | undefined, text: string, idempotencyKey: string): void;
|
|
236
|
+
export declare function enqueueAgentNotice(api: OpenClawPluginApi, sessionKey: string | undefined, upgrade: UpgradeRequired): void;
|
|
237
|
+
/** Agent-facing note for a `flag` match — surfaced via the next-turn injection
|
|
238
|
+
* so `flag` is observable to the model (not just the operator log), matching
|
|
239
|
+
* the `additionalContext` flag notes on Claude Code / Codex. */
|
|
240
|
+
export declare function flagNote(binding: ReflexBinding, verdict: Verdict, subject: string): string;
|
|
241
|
+
/** Outbound hook: surface this session's pending fail-open upgrade notice as a
|
|
242
|
+
* distinct `context` (footer) block on the reply the user sees, once per
|
|
243
|
+
* session. This is the one reliable user-visible surface on OpenClaw —
|
|
244
|
+
* context/prompt hooks are model-facing only (see FRAMEWORKS.md OpenClaw
|
|
245
|
+
* notes).
|
|
246
|
+
*
|
|
247
|
+
* The model's response is never mutated or dropped:
|
|
248
|
+
* - When the reply already carries a presentation, we append the notice as a
|
|
249
|
+
* trailing context block and copy every existing block/field unchanged.
|
|
250
|
+
* - When the reply is plain text, we wrap that text VERBATIM in a `text`
|
|
251
|
+
* block and add the context block after it. The model's words become the
|
|
252
|
+
* single source of truth (the presentation), so we drop the now-redundant
|
|
253
|
+
* top-level `text` to avoid double-rendering on channels that show both
|
|
254
|
+
* (e.g. Teams); core regenerates plain-channel fallback text from these
|
|
255
|
+
* blocks (message-presentation.md degradation rules: `text` blocks render
|
|
256
|
+
* as paragraphs, `context` blocks as compact lines).
|
|
257
|
+
*
|
|
258
|
+
* Returns a NEW payload object; the input event.payload is never mutated. */
|
|
259
|
+
export declare function appendUpgradeNotice(event: ReplyPayloadSendingEvent, ctx: MessageContext): ReplyPayloadSendingResult | undefined;
|
|
260
|
+
export declare function forgetSession(event: SessionEndEvent): void;
|
|
261
|
+
/** Read the run's stashed request + the session's original task as task-context
|
|
262
|
+
* sources, or undefined if neither is available. */
|
|
263
|
+
export declare function recallTaskContext(api: OpenClawPluginApi, ctx: ToolContext): TaskContextSources | undefined;
|
|
264
|
+
/** Render one completed tool call as a trajectory line. */
|
|
265
|
+
export declare function renderAction(event: AfterToolCallEvent): string;
|
|
266
|
+
/** Capture hook: append this completed tool call to the run's trajectory. */
|
|
267
|
+
export declare function rememberAction(api: OpenClawPluginApi, event: AfterToolCallEvent, ctx: ToolContext): void;
|
|
268
|
+
/** Read the run's trajectory back as an "Actions this turn:" block, or null. */
|
|
269
|
+
export declare function recallTrajectory(api: OpenClawPluginApi, ctx: ToolContext): string | null;
|
|
270
|
+
/** Resolve project standing instructions from disk (AGENTS.md, else CLAUDE.md)
|
|
271
|
+
* at `cwd`. Independent of the event, so it works even when OpenClaw doesn't
|
|
272
|
+
* surface the conversation. null if none present. */
|
|
273
|
+
export declare function resolveStandingInstructions(cwd: string): string | null;
|
|
274
|
+
export interface EvaluateOptions {
|
|
275
|
+
fetchImpl?: typeof fetch;
|
|
276
|
+
timeoutMs?: number;
|
|
277
|
+
taskContext?: TaskContextSources;
|
|
278
|
+
cwd?: string;
|
|
279
|
+
trajectory?: string | null;
|
|
280
|
+
sessionKey?: string;
|
|
281
|
+
onFailOpenUpgrade?: (upgrade: UpgradeRequired) => void;
|
|
282
|
+
onFlag?: (note: string) => void;
|
|
283
|
+
}
|
|
284
|
+
export declare class UpgradeRequired extends Error {
|
|
285
|
+
readonly kind: "rate_limit" | "subscription";
|
|
286
|
+
/** One-line notice shown to the user (appended to the outbound reply). */
|
|
287
|
+
readonly userNotice: string;
|
|
288
|
+
/** Notice injected into the model's next turn, so the agent itself learns
|
|
289
|
+
* enforcement was degraded even when there's no outbound channel. */
|
|
290
|
+
readonly agentNotice: string;
|
|
291
|
+
constructor(kind: "rate_limit" | "subscription", userNotice: string, agentNotice: string);
|
|
292
|
+
}
|
|
293
|
+
/** Dispatch to the configured evaluator backend. Mirrors the Python
|
|
294
|
+
* reference's four evaluator classes (reflexes/evaluators/*.py) — same
|
|
295
|
+
* endpoints, prompts, and label parsing — so a reflexes.yaml behaves
|
|
296
|
+
* identically whether evaluated by the Python integration or this plugin. */
|
|
297
|
+
export declare function evaluate(config: ReflexesConfig, criteria: string, content: string, opts?: EvaluateOptions): Promise<Verdict>;
|
|
298
|
+
/** Batch-evaluate many policies against one content in a single /v1/systemone
|
|
299
|
+
* call. One Verdict per criteria, in order. Mirrors evaluateZentropi's retry +
|
|
300
|
+
* fail-loud-as-throw contract (the caller fails open). */
|
|
301
|
+
export declare function evaluateManySystemOne(config: ReflexesConfig, criteriaList: string[], content: string, opts?: EvaluateOptions): Promise<Verdict[]>;
|
|
302
|
+
export declare function denyReason(binding: ReflexBinding, subject?: string): string;
|
|
303
|
+
/** Self-correction instruction for a denied response (before_agent_finalize
|
|
304
|
+
* `retry.instruction`). The harness re-runs the model with this prepended. */
|
|
305
|
+
export declare function reviseInstruction(binding: ReflexBinding): string;
|
|
306
|
+
/** Default cap on concurrent evaluator calls per trigger fire. */
|
|
307
|
+
export declare const DEFAULT_MAX_CONCURRENT = 10;
|
|
308
|
+
/**
|
|
309
|
+
* Core hook logic, framework-agnostic and fully unit-testable.
|
|
310
|
+
* Returns undefined to allow, or a block result per OpenClaw's
|
|
311
|
+
* BeforeToolCallResult contract.
|
|
312
|
+
*/
|
|
313
|
+
export declare function checkToolCall(event: BeforeToolCallEvent, config: ReflexesConfig | null, opts?: EvaluateOptions): Promise<BeforeToolCallResult | undefined>;
|
|
314
|
+
/**
|
|
315
|
+
* Core `before_response` logic: evaluate the agent's final reply against the
|
|
316
|
+
* bound `before_response` policies. On deny, return `{ action: "revise" }` so
|
|
317
|
+
* OpenClaw blocks finalization and re-runs the model with the policy text as
|
|
318
|
+
* the revision instruction (the before_agent_finalize self-correct loop).
|
|
319
|
+
*/
|
|
320
|
+
export declare function checkResponse(event: FinalizeEvent, config: ReflexesConfig | null, opts?: EvaluateOptions): Promise<FinalizeResult | undefined>;
|
|
321
|
+
/**
|
|
322
|
+
* Core `on_input` logic: evaluate the user's prompt against the bound `on_input`
|
|
323
|
+
* policies BEFORE it reaches the model, via OpenClaw's `before_agent_run` gate.
|
|
324
|
+
* On deny, return `{ outcome: "block" }` so OpenClaw never submits the prompt.
|
|
325
|
+
*
|
|
326
|
+
* `before_agent_run` is FAIL-CLOSED in OpenClaw (a void/thrown result blocks the
|
|
327
|
+
* prompt), so this ALWAYS returns an explicit decision and swallows every
|
|
328
|
+
* internal error into `{ outcome: "pass" }` — Reflexes fails OPEN, never blocking
|
|
329
|
+
* a user because our own check broke.
|
|
330
|
+
*/
|
|
331
|
+
export declare function checkInput(event: BeforeAgentRunEvent, config: ReflexesConfig | null, opts?: EvaluateOptions): Promise<InputGateDecision>;
|
|
332
|
+
/** OpenClaw plugin entry. Config is loaded once at registration. Capture hooks
|
|
333
|
+
* (`llm_input`, `message_received`, `session_end`, `after_tool_call`) build the
|
|
334
|
+
* task context + trajectory; `before_agent_run` (on_input), `before_tool_call`,
|
|
335
|
+
* and `before_agent_finalize` (before_response) enforce policies;
|
|
336
|
+
* `reply_payload_sending` adds a fail-open upgrade notice as
|
|
337
|
+
* a distinct footer block so the user sees when enforcement was degraded (the
|
|
338
|
+
* agent is also informed directly via a next-turn injection). */
|
|
339
|
+
declare const entry: {
|
|
340
|
+
id: string;
|
|
341
|
+
name: string;
|
|
342
|
+
description: string;
|
|
343
|
+
register(api: OpenClawPluginApi): void;
|
|
344
|
+
};
|
|
345
|
+
export default entry;
|