@percepteye/agent-flywheel 0.1.0 → 0.1.2

package/README.md

@@ -37,15 +37,15 @@ One plugin. Zero runtime dependencies. Zero lines changed in your agent.
      regardless of what CI did.
 
      Separately: the `tests` badge below is hardcoded and nothing checks it;
-     its 434 was true on 2026-09-14 (it had drifted to 373 while the suite
-     grew). Re-derive with `npm test` (prints "tests 434" / "skipped 0")
+     its 490 was true on 2026-09-15 (it had drifted to 373 while the suite
+     grew). Re-derive with `npm test` (prints "tests 490" / "skipped 0")
      before trusting it — the Python SDK's equivalent badge had drifted to 54
      short. -->
 [![npm](https://img.shields.io/npm/v/@percepteye/agent-flywheel?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=3b82f6)](https://www.npmjs.com/package/@percepteye/agent-flywheel)
 [![node](https://img.shields.io/badge/node-%E2%89%A522.22.3-8b5cf6?style=for-the-badge&logo=nodedotjs&logoColor=white)](package.json)
 [![runtime dependencies](https://img.shields.io/badge/runtime_deps-0-f59e0b?style=for-the-badge)](#-why-it-earns-its-place)
 [![lines changed in your agent](https://img.shields.io/badge/lines_changed_in_your_agent-0-ec4899?style=for-the-badge)](#-install-in-one-call)
-[![tests](https://img.shields.io/badge/tests-434_·_0_skips-22c55e?style=for-the-badge)](#-develop)
+[![tests](https://img.shields.io/badge/tests-490_·_0_skips-22c55e?style=for-the-badge)](#-develop)
 [![license](https://img.shields.io/badge/license-MIT-14b8a6?style=for-the-badge)](LICENSE)
 
 <img src="docs/assets/flywheel-overview.gif"
@@ -70,7 +70,7 @@ No container to build. No cluster to run. No GPU to provision. No inbound port t
 |:--|:--|
 | 🔁 **A continual-learning loop** | your agent runs graded tasks, its real outcomes go back, and the next model is trained on *this agent's* work — not a generic benchmark |
 | 🤖 **Autonomous post-training** | task generation, grading, dataset construction, training and promotion happen on our side. You build none of it |
-| 🧪 **Honest discovery** | the plugin reads the assembled prompt and effective model; current OpenClaw does not expose tools on `llm_input`, so the catalogue stays explicitly incomplete instead of being invented |
+| 🧪 **Honest discovery** | the plugin reads the assembled prompt and effective model; current OpenClaw does not expose tools on `llm_input`, so the catalogue stays explicitly incomplete instead of being invented — until you declare it with [`describe`](#-configuration) |
 | 📈 **Honest telemetry on day one** | your agent's true tool-failure rate, recorded locally, with **no account and no network** |
 | 📡 **Production observability** | capture the turns you actually serve — the user's message, the tool calls, the answer — and turn live traffic into evidence |
 | ✅ **The approved pair, applied** | training co-optimizes a system prompt alongside the model. Once *a person on your side approves each*, your production install runs **both** — the prompt, and the checkpoint it was certified with. No redeploy; one switch each to stop |
@@ -319,9 +319,29 @@ Scalar settings are settable two ways: in your OpenClaw config under `plugins.en
 | `applyPrompt` | `PERCEPTEYE_APPLY_PROMPT` | on | `0` subscribes no prompt hook and does not fetch the prompt text |
 | `applyModel` | `PERCEPTEYE_APPLY_MODEL` | on | `0` subscribes no model hook and registers no provider |
 | `executionSnapshot` | *(config only)* | *(none)* | opaque SHA-256 components from the host adapter, its completeness assertion, and optionally an exact startup prompt/tool/provider/model observation. Exact startup evidence binds registration and claims to the same SDK-authored execution identity later reported; missing, invalid, lossy, or conflicting evidence abstains |
+| `introspect` | `PERCEPTEYE_INTROSPECT` | on | `0`/`false`/`no`/`off` registers this agent with no description at all, which the control plane records as your opt-out, and authors no execution identity. **The one switch where config does not win:** a refusal from either side stands, as it does in the Python SDK |
+| `describe` | *(config only)* | *(none)* | the agent's own `system_prompt`, `tools` and `model`, for what this plugin cannot observe — OpenClaw's `llm_input` carries no tools. See below |
 
 The snapshot contains `adapterName`, `executionIdentityComplete: true`, and a non-empty `executionComponents` object whose values are lowercase SHA-256 digests. An adapter that can resolve the full execution before work is claimed may also provide `startupObservation: {systemPrompt, tools, provider, model}`. Core runs startup and per-run evidence through the same canonical descriptor; it never accepts a caller-authored final digest. Component names belong to the adapter, and core does not assign them meaning. The resulting `execution_sha256` identifies the observed execution scaffold, not the serving policy, and this package does not generate training hints; those decisions belong downstream where evidence from multiple turns can be compared.
 
+**`describe`** says what this plugin cannot see. OpenClaw's `llm_input` carries no tool list, so on its own this plugin registers an agent whose tools are unknown, and no task can be generated for it. Declare them:
+
+```json
+"plugins": { "entries": { "agent-flywheel": { "config": { "describe": {
+  "system_prompt": "You triage support tickets.",
+  "tools": [{ "name": "lookup_ticket", "description": "Read one ticket.",
+              "input_schema": { "type": "object", "properties": { "id": { "type": "string" } } },
+              "read_only": true }]
+} } } } }
+```
+
+It is the Python SDK's `describe=`, read by the same rules, and a cross-language test holds the two equal: the same record, and the same refusals, for anything JSON carries — except an integer beyond 2⁵³ inside a schema, which JavaScript holds rounded.
+- **`tools`** is the list your agent sends its model: OpenAI function specs, Anthropic tools, or `{name, description, input_schema, read_only}`. A name and a description must be strings. `read_only: true` goes at the top level of an entry, whichever shape.
+- **`model`** is a name, or `{model_name, provider, temperature, max_tokens}`: `temperature` a finite number, and `max_tokens` a whole number from 1 to 2⁵³ − 1.
+- **What you declare wins** over what was observed, where you gave it. Anything you leave out still comes from observation. With nothing observed, the record names this plugin's host, `framework: "openclaw"`, where the Python SDK — which cannot know — says `custom`.
+- **It is your word, not an observation,** so it anchors no execution identity. If you also configured `executionSnapshot`, a startup warning says the identity is withheld.
+- **A bad declaration does not stop the plugin**, because a throw would take local capture down with it — and the config schema accepts any `describe` value, so OpenClaw never refuses the plugin over one either. It is dropped with a warning that names the cause, the same one the Python SDK refuses with, and the agent registers only what was observed.
+
 Three more environment variables name directories rather than switching anything. `PERCEPTEYE_HOME` relocates everything this package writes (default `~/.percepteye`); `PERCEPTEYE_CAPTURE_DIR` overrides just the production turn capture (default `$PERCEPTEYE_HOME/captured`); and `PERCEPTEYE_TRAJECTORY_DIR` names where a training rollout's outcomes go, which the rollout driver sets per rollout.
 
 One host setting is not ours and has no environment form: `plugins.entries.agent-flywheel.hooks.allowConversationAccess`, which OpenClaw itself requires before it will deliver conversation hooks to a non-bundled plugin. See [Install](#-install-in-one-call).
@@ -358,7 +378,7 @@ One host setting is not ours and has no environment form: `plugins.entries.agent
 ## 🛠 Develop
 
 ```bash
-npm test     # 434 tests, no install step — node:test, zero dependencies
+npm test     # 490 tests, no install step — node:test, zero dependencies
 ```
 
 The suite includes payloads captured verbatim from a live OpenClaw run (`test/host-fixtures.test.js`). If a future OpenClaw changes the shape, those fail — rather than someone discovering it months later from bad training data.

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-flywheel",
   "name": "Agent Flywheel",
   "description": "Close the loop on your OpenClaw or DeepSeek Harness agent: record what your tools actually did — ok, failed or unknown — claim graded rollouts in training mode, and report them back. Never alters a tool result; set PERCEPTEYE_AGENT_MODE=production for a serving install, which claims no rollouts and starts no turn but does capture the turns you serve and apply the system prompt and the model your control plane has approved.",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "providers": [
     "percepteye-flywheel"
   ],
@@ -30,21 +30,27 @@
       "capture": {
         "type": [
           "string",
-          "boolean"
+          "boolean",
+          "number",
+          "null"
         ],
         "description": "Set false/0/off to disable local capture entirely. Unset means PERCEPTEYE_CAPTURE, then on."
       },
       "applyPrompt": {
         "type": [
           "string",
-          "boolean"
+          "boolean",
+          "number",
+          "null"
         ],
         "description": "Set false/0/off to stop applying the control plane's approved system prompt in production mode. Unset means PERCEPTEYE_APPLY_PROMPT, then on."
       },
       "applyModel": {
         "type": [
           "string",
-          "boolean"
+          "boolean",
+          "number",
+          "null"
         ],
         "description": "Set false/0/off to stop pointing this agent at the control plane's approved model in production mode. Unset means PERCEPTEYE_APPLY_MODEL, then on. Needs hooks.allowConversationAccess=true to take effect at all."
       },
@@ -125,6 +131,18 @@
           "serving"
         ],
         "description": "training: this install claims rollouts and drives turns. production: claims no rollout and starts no turn -- those hooks are never registered -- but captures the turns you serve and applies the system prompt your control plane approved. Unset means PERCEPTEYE_AGENT_MODE, then training; a value here overrides the environment."
+      },
+      "introspect": {
+        "type": [
+          "string",
+          "boolean",
+          "number",
+          "null"
+        ],
+        "description": "Set false/0/off to register this agent with no description at all; the control plane records that as your opt-out. PERCEPTEYE_INTROSPECT=0 refuses too, whatever this says. Unset means on."
+      },
+      "describe": {
+        "description": "The agent's own description, for what this plugin cannot observe (OpenClaw's llm_input carries no tools): system_prompt, tools (the list the agent sends its model -- OpenAI function specs, Anthropic tools, or {name, description, input_schema, read_only}) and model (a name, or {model_name, provider, temperature, max_tokens}). What you declare wins where given; it anchors no execution identity."
       }
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percepteye/agent-flywheel",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Close the loop on your OpenClaw or DeepSeek Harness agent: record what your tools actually did — ok, failed or unknown — claim graded rollouts in training mode, and report them back. Never alters a tool result; set PERCEPTEYE_AGENT_MODE=production for a serving install, which claims no rollouts and starts no turn but does capture the turns you serve and apply the system prompt and the model your control plane has approved.",
   "license": "MIT",
   "author": "PerceptEye",

package/src/capture.js

@@ -63,6 +63,8 @@ import { randomUUID } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { applyDeclaration } from "./declaration.js";
+import { FRAMEWORK } from "./describe.js";
 import { conversationAccessGranted, lastAssistantText } from "./host.js";
 import { ControlPlaneClient, SDK_UA } from "./http.js";
 import { percepteyeHome } from "./session.js";
@@ -471,7 +473,7 @@ export const GATEWAY_STOP = "gateway_stop";
  */
 export function registerTurnCapture(api, {
   config, turns, pluginId, logger = null, env = process.env,
-  makeTransport = defaultTransport,
+  makeTransport = defaultTransport, declaration = null,
 }) {
   if (!turns || typeof api?.on !== "function") return null;
   const root = captureRoot(env);
@@ -555,7 +557,7 @@ export function registerTurnCapture(api, {
     //
     // NOT AWAITED: `register()` must return to the host synchronously, and a
     // control plane that is slow or down must not delay a plugin load.
-    started = enrol({ transport, config, pluginId, logger })
+    started = enrol({ transport, config, pluginId, logger, declaration })
       .then(() => announce({ transport, uploader, config, pluginId, logger, env }));
   } else {
     logger?.info?.(
@@ -606,34 +608,30 @@ function defaultTransport(config) {
  * share one route, and only one of them survived the split. This is the other
  * one, back as its own call, which is why `announce()` still performs no write.
  *
- * `discovered_agent: null` -- INTROSPECTION_UNREADABLE. It is the TRUE state of
- * the three rather than the convenient one, and the other two are wrong for
- * different reasons:
+ * `discovered_agent` -- THREE ANSWERS, one per case, each the true one, asked
+ * exactly as the Python SDK's `attach()` asks them:
  *
- *   OMITTING the key records `disabled`, which means "the customer opted out
- *   of introspection". Nothing here offers them that choice -- this package
- *   has no `introspect` setting and reads no PERCEPTEYE_INTROSPECT -- so it
- *   would assert a decision nobody made. It is also the DESTRUCTIVE state:
- *   `FlywheelAgentRepository.upsert` writes `disabled` onto the row
- *   unconditionally, which stops that agent's description driving workflow
- *   generation. That is precisely the side effect `announce()` describes and
- *   the reason the old registration had to go, so re-creating it here would
- *   undo one fix while claiming another.
+ *   OMITTED when the customer refused introspection (`introspect: false` or
+ *   PERCEPTEYE_INTROSPECT=0). The control plane records that as `disabled`,
+ *   which stops the stored description driving workflow generation -- the
+ *   instruction the customer gave. Omitting it for anyone else would assert a
+ *   decision nobody made, which is why this used to be the one state never
+ *   sent: before the switch existed, nobody could have made it.
  *
- *   A DESCRIPTION cannot honestly be sent. `describe.js` is the only source of
- *   one and it writes into PERCEPTEYE_TRAJECTORY_DIR, which production mode
- *   does not set -- so the describer is inert here -- and even where it is
- *   active `llm_input` first fires on the first model call, strictly after
- *   this. Waiting for one would put registration behind a CONVERSATION hook
- *   the host drops for a non-bundled plugin by default, i.e. this same defect
- *   again for the majority of installs.
+ *   THE DECLARATION, when the operator gave one (`describe`, see
+ *   declaration.js): their word about the agent, and the only description
+ *   this process can honestly send. The control plane keeps a stored
+ *   catalogue that a declaration without tools did not observe.
  *
- *   NULL is what is left and what is true: we looked, and we have no
- *   description. It is also the one state `upsert` treats as a fact about the
- *   control plane's framework coverage rather than a retraction by the
- *   customer -- a row that already holds a tool catalogue keeps BOTH the
- *   catalogue and its state -- so a production process re-registering on every
- *   restart cannot erase what a training run established.
+ *   NULL otherwise: we looked, and we have no description. `describe.js`, the
+ *   only observer, writes into PERCEPTEYE_TRAJECTORY_DIR, which production
+ *   mode does not set, and `llm_input` first fires on the first model call,
+ *   strictly after this -- waiting for it would put registration behind a
+ *   CONVERSATION hook the host drops for a non-bundled plugin by default. A
+ *   production null changes nothing the control plane holds, neither the
+ *   stored description nor its state (a new agent is `not_described`), so a
+ *   process re-registering on every restart cannot erase what a training run
+ *   established.
  *
  * NEVER REJECTS, and never throws into its caller. A refused or unreachable
  * control plane must not cost the verdict read, local capture (which needs no
@@ -647,7 +645,7 @@ function defaultTransport(config) {
  * package has already paid for one exported control-plane call that nothing
  * called: `AttachTransport.register` itself, which is the defect above.
  */
-function enrol({ transport, config, pluginId, logger = null }) {
+function enrol({ transport, config, pluginId, logger = null, declaration = null }) {
   return Promise.resolve()
     .then(() => transport.register({
       agent_id: config.agentId,
@@ -673,8 +671,15 @@ function enrol({ transport, config, pluginId, logger = null }) {
       concurrency: 1,
       input_shape: "text",
       entrypoint: "openclaw-plugin",
-      // See the docstring. `null`, never omitted and never invented.
-      discovered_agent: null,
+      // See the docstring: omitted on a refusal, the declaration when there
+      // is one, and otherwise null -- never invented. Last, where it always
+      // was, so an undeclared registration is the same bytes as before. The
+      // framework is the host's: this plugin knows it runs in OpenClaw.
+      ...(config.introspect === false ? {} : {
+        discovered_agent: applyDeclaration(declaration, {
+          reflected: null, agentName: config.agentId, framework: FRAMEWORK,
+        }) ?? null,
+      }),
     }))
     .then(() => true)
     .catch((err) => {
@@ -706,9 +711,10 @@ function enrol({ transport, config, pluginId, logger = null }) {
  * writes -- re-asking costs a read and nothing else, which is the whole point
  * of the route -- but the row the verdict is computed from still has to be
  * created by somebody, and `enrol()` above is now the one that does it. When
- * that was left out, this read answered "not registered" forever. The explicit
- * `discovered_agent: null` it sends is no longer a workaround for a side
- * effect: it is the honest state, for the reasons `enrol()` gives.
+ * that was left out, this read answered "not registered" forever. What it
+ * sends as `discovered_agent` -- null, a declaration, or nothing under the
+ * customer's opt-out -- is no longer a workaround for a side effect: each is
+ * the honest state, for the reasons `enrol()` gives.
  */
 export function announce({ transport, uploader, config, pluginId, logger }) {
   return Promise.resolve()

package/src/config.js

@@ -47,6 +47,12 @@ export const PLUGIN_ID = "agent-flywheel";
  * rollouts and started unattended turns anyway, and the operator got no signal
  * because the production-mode log is on the branch that was never taken.
  *
+ * THE SAME HOST REFUSES A WRONG TYPE THE SAME WAY: a value its validator
+ * rejects fails the plugin load. So the on/off switches take a NUMBER too --
+ * `capture: 0` is documented as off, and a schema of string|boolean refused it
+ * and skipped the plugin -- and NULL, which `resolveConfig` reads as unset;
+ * and `describe` declares no type at all.
+ *
  * `resolveConfig` below is the ONE place a default is decided. A schema default
  * is a second answer to a question already answered there, and this host turns
  * it into the winning one. `test/config-gate.test.js` asserts the absence.
@@ -77,20 +83,20 @@ export const CONFIG_SCHEMA = {
       description: "Override the control-plane base URL.",
     },
     capture: {
-      type: ["string", "boolean"],
+      type: ["string", "boolean", "number", "null"],
       description:
         "Set false/0/off to disable local capture entirely. Unset means " +
         "PERCEPTEYE_CAPTURE, then on.",
     },
     applyPrompt: {
-      type: ["string", "boolean"],
+      type: ["string", "boolean", "number", "null"],
       description:
         "Set false/0/off to stop applying the control plane's approved " +
         "system prompt in production mode. Unset means " +
         "PERCEPTEYE_APPLY_PROMPT, then on.",
     },
     applyModel: {
-      type: ["string", "boolean"],
+      type: ["string", "boolean", "number", "null"],
       description:
         "Set false/0/off to stop pointing this agent at the control " +
         "plane's approved model in production mode. Unset means " +
@@ -150,6 +156,27 @@ export const CONFIG_SCHEMA = {
         "PERCEPTEYE_AGENT_MODE, then training; a value here overrides the " +
         "environment.",
     },
+    introspect: {
+      type: ["string", "boolean", "number", "null"],
+      description:
+        "Set false/0/off to register this agent with no description at all; " +
+        "the control plane records that as your opt-out. " +
+        "PERCEPTEYE_INTROSPECT=0 refuses too, whatever this says. Unset " +
+        "means on.",
+    },
+    // NO `type`, deliberately. A value the host's validator refuses fails the
+    // whole plugin load and takes local capture down with it, so any value
+    // passes here and declaration.js decides -- refusing a bad one with a
+    // warning, the plugin still loaded.
+    describe: {
+      description:
+        "The agent's own description, for what this plugin cannot observe " +
+        "(OpenClaw's llm_input carries no tools): system_prompt, tools (the " +
+        "list the agent sends its model -- OpenAI function specs, Anthropic " +
+        "tools, or {name, description, input_schema, read_only}) and model " +
+        "(a name, or {model_name, provider, temperature, max_tokens}). What " +
+        "you declare wins where given; it anchors no execution identity.",
+    },
   },
 };
 
@@ -244,6 +271,18 @@ export function resolveConfig(pluginConfig = {}, env = process.env) {
     // Adapter-owned opaque evidence. Validation and fail-closed reconciliation
     // live with the identity code; configuration only transports the snapshot.
     executionSnapshot: pluginConfig.executionSnapshot ?? null,
+    // CONSENT to describe this agent, asked as the Python SDK asks it and
+    // refusable from EITHER side: `introspect: false` here (Python's
+    // `serve(introspect=False)`) or PERCEPTEYE_INTROSPECT=0 (for an operator
+    // who cannot edit the config). Unlike the switches above, neither side
+    // overrides the other -- one refusal is enough, as it is in Python.
+    introspect:
+      enabledUnlessOff(pluginConfig.introspect, undefined) &&
+      enabledUnlessOff(undefined, env.PERCEPTEYE_INTROSPECT),
+    // The operator's own description, transported only. It is checked in
+    // index.js, where a bad one can be refused loudly without failing the
+    // plugin load; see declaration.js.
+    describe: pluginConfig.describe ?? null,
     contributing: Boolean(apiKey),
   };
 }

package/src/declaration.js

@@ -0,0 +1,388 @@
+/**
+ * `describe`: an agent describing itself when nothing can read it.
+ *
+ * The Node end of the Python SDK's `agent_flywheel/declaration.py`, rule for
+ * rule, so a declaration registers the same description from either SDK. The
+ * Python repository's `tests/test_describe_parity.py` runs this module beside
+ * that one over one table and holds them equal: the same wire record, and the
+ * same refusals.
+ *
+ * WHY THE NODE PLUGIN NEEDS IT. OpenClaw's `llm_input` carries no tools, so
+ * this plugin's own observation of an agent never has a catalogue (see
+ * `describe.js`), and a catalogue is what task generation needs. The operator
+ * knows what the agent sends its model; this is where they say it:
+ *
+ *   plugins.entries.agent-flywheel.config.describe = {
+ *     system_prompt: "...",
+ *     tools: [ ...the tool list the agent sends its model ],
+ *   }
+ *
+ * THE CUSTOMER'S WORD WINS, AND ONLY WHERE THEY GAVE IT. Declared fields
+ * replace what was observed; anything left out still comes from observation.
+ * Leaving `tools` out never means "no tools" -- that is `tools: []`.
+ *
+ * PYTHON'S PARSER, NOT `normalizeTool`. The host observation's parser reads
+ * OpenClaw shapes and scrubs what it copies. A declaration is read exactly as
+ * the Python SDK reads it -- OpenAI function specs, Anthropic tools, or the
+ * protocol's own `{name, description, input_schema, read_only}` -- because
+ * the one thing that matters about a declared tool is that both SDKs register
+ * the same record for it. That holds for anything JSON carries, with one
+ * limit JavaScript imposes: an integer beyond 2**53 inside a schema is held
+ * rounded here. Where the two languages would otherwise part -- whitespace,
+ * coercion, number types, sort order -- the rule is Python's, or is one both
+ * can keep: names and descriptions must be strings, and `max_tokens` a whole
+ * number both hold exactly.
+ *
+ * NOT EVIDENCE. A declaration is what the customer says the agent does, not an
+ * observation of what ran, so a declared description anchors no execution
+ * identity: `index.js` withholds the fingerprint whenever this module
+ * contributed.
+ */
+import { ConfigurationError } from "./errors.js";
+import { compareStrings } from "./execution-identity.js";
+
+/** `source_type` of a description a declaration contributed to. */
+export const SOURCE_TYPE = "sdk_declared";
+
+/**
+ * The registration projection's prompt bound: the Python SDK's
+ * `_MAX_PROMPT_CHARS`, counted in code points as Python counts them.
+ */
+export const MAX_PROMPT_CHARS = 20_000;
+
+const KEYS = ["model", "system_prompt", "tools"];
+const MODEL_KEYS = ["max_tokens", "model_name", "provider", "temperature"];
+
+/**
+ * Python's `str.strip()`: exactly the characters `str.isspace()` names. JS's
+ * `trim()` also strips U+FEFF and keeps U+001C-U+001F and U+0085, so a tool
+ * named "\u0085" was a tool here and nothing in Python.
+ */
+const PY_SPACE = "\\t\\n\\v\\f\\r\\x1c-\\x20\\x85\\xa0\\u1680\\u2000-\\u200a" +
+  "\\u2028\\u2029\\u202f\\u205f\\u3000";
+const PY_STRIP = new RegExp(`^[${PY_SPACE}]+|[${PY_SPACE}]+$`, "g");
+const strip = (text) => text.replace(PY_STRIP, "");
+
+/**
+ * Python's truthiness, where the Python end branches on it: an empty array or
+ * object is FALSE there and true here, and a declaration must not turn into a
+ * different tool on the Node side because of it.
+ */
+function truthy(v) {
+  if (Array.isArray(v)) return v.length > 0;
+  if (isMapping(v)) return Object.keys(v).length > 0;
+  return Boolean(v);
+}
+
+/**
+ * A JSON object: Python's `Mapping`. A PLAIN object only -- a Promise (an
+ * async `describe`), a Map or a class instance is not a declaration, and
+ * reading one as an empty object declared nothing in silence.
+ */
+function isMapping(v) {
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+/** The JSON type a refusal names: one vocabulary both SDKs print alike. */
+function jsonType(v) {
+  if (v === null || v === undefined) return "null";
+  if (typeof v === "boolean") return "boolean";
+  if (typeof v === "number") return "number";
+  if (typeof v === "string") return "string";
+  if (Array.isArray(v)) return "array";
+  if (isMapping(v)) return "object";
+  if (typeof v !== "object") return typeof v;
+  try {
+    return v.constructor?.name ?? "object";
+  } catch {
+    return "object";
+  }
+}
+
+/** Python's `json.dumps(str)`: `JSON.stringify` with non-ASCII escaped. */
+function jsonAscii(text) {
+  return JSON.stringify(text).replace(/[\u0080-\uffff]/g,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+
+/** Key names as a JSON array, sorted by code point, as Python renders them. */
+function keyList(keys) {
+  return `[${[...keys].sort(compareStrings).map(jsonAscii).join(", ")}]`;
+}
+
+/** A value quoted back in a refusal. Never throws: a BigInt or a cycle is still a refusal. */
+function render(v) {
+  let text;
+  try {
+    text = JSON.stringify(v);
+  } catch {
+    text = undefined;
+  }
+  if (text === undefined) {
+    try {
+      text = String(v);
+    } catch {
+      text = Object.prototype.toString.call(v);
+    }
+  }
+  return text.slice(0, 120);
+}
+
+/**
+ * `describe` validated and parsed, calling it if it is a function.
+ *
+ * `null` when nothing was declared -- including an object whose every value
+ * is null. A function that throws is refused the same way, naming `describe`.
+ *
+ * @returns {{system_prompt: string|null, tools: object[]|null, model: object|null}|null}
+ * @throws {ConfigurationError}
+ */
+export function resolveDeclaration(describe) {
+  if (describe === null || describe === undefined) return null;
+  let spec;
+  if (typeof describe === "function") {
+    try {
+      spec = describe();
+    } catch (err) {
+      if (err instanceof ConfigurationError) throw err;
+      // Whatever was thrown -- a Symbol, a null-prototype object -- becomes a
+      // refusal; reading its name or message must not throw a second time.
+      let name;
+      let detail;
+      try {
+        name = err?.constructor?.name ?? typeof err;
+        detail = typeof err?.message === "string" ? err.message : render(err);
+      } catch {
+        name = typeof err;
+        detail = render(err);
+      }
+      throw new ConfigurationError(`describe= raised ${name}: ${detail}`);
+    }
+  } else {
+    spec = describe;
+  }
+  if (!isMapping(spec)) {
+    throw new ConfigurationError(
+      "describe= must be a mapping (or a callable returning one), got " +
+      jsonType(spec));
+  }
+  const unknown = Object.keys(spec).filter((k) => !KEYS.includes(k));
+  if (unknown.length) {
+    throw new ConfigurationError(
+      `describe= got unknown key(s) ${keyList(unknown)}; it accepts ` +
+      keyList(KEYS));
+  }
+  const prompt = spec.system_prompt ?? null;
+  const tools = spec.tools ?? null;
+  const model = spec.model ?? null;
+  if (prompt !== null && typeof prompt !== "string") {
+    throw new ConfigurationError("describe['system_prompt'] must be a string");
+  }
+  if (tools !== null && !Array.isArray(tools)) {
+    throw new ConfigurationError(
+      "describe['tools'] must be a list -- the tools you send the model");
+  }
+  if (model !== null && typeof model !== "string" && !isMapping(model)) {
+    throw new ConfigurationError(
+      "describe['model'] must be a model name or a mapping of " +
+      "provider / model_name / temperature / max_tokens");
+  }
+  if (prompt === null && tools === null && model === null) return null;
+  return {
+    system_prompt: prompt === null ? null : codePoints(prompt, MAX_PROMPT_CHARS),
+    tools: tools === null ? null : declaredTools(tools),
+    model: model === null ? null : declaredModel(model),
+  };
+}
+
+/** `text` cut to `max` code points, as a Python slice cuts it. */
+function codePoints(text, max) {
+  if (text.length <= max) return text;
+  return Array.from(text).slice(0, max).join("");
+}
+
+/**
+ * Python's `_tools_from_request` for one entry: the OpenAI envelope, or a flat
+ * tool with a name. The legacy flat `functions` shape spells the schema
+ * `parameters`, so that is read when `input_schema` is absent.
+ */
+function fromRequest(entry) {
+  if (!isMapping(entry)) return null;
+  const fn = entry.function;
+  if (isMapping(fn)) {
+    return {
+      name: fn.name, description: fn.description,
+      input_schema: fn.parameters, original_format: "openai_function",
+    };
+  }
+  if (truthy(entry.name)) {
+    return {
+      name: entry.name, description: entry.description,
+      input_schema: Object.hasOwn(entry, "input_schema")
+        ? entry.input_schema : entry.parameters,
+      original_format: "anthropic_tool",
+    };
+  }
+  return null;
+}
+
+/** Python's `_tool_from_wire`: null when there is no usable name. */
+function fromWire(raw) {
+  const name = strip(truthy(raw.name) ? raw.name : "");
+  if (!name) return null;
+  return {
+    name,
+    description: truthy(raw.description) ? raw.description : "",
+    input_schema: isMapping(raw.input_schema) ? raw.input_schema : {},
+    original_format: raw.original_format,
+  };
+}
+
+/**
+ * The declared tools, in the wire's tool shape. A tool the parser cannot read
+ * is the customer's mistake and is said at startup rather than dropped: a
+ * silently shorter catalogue is a smaller task universe nobody chose. So is a
+ * schema that is not a mapping, a `read_only` that is not a boolean or sits
+ * inside `function` where the parser would not see it, and a name or
+ * description that is not a string -- coerced, it became text no two
+ * languages agree on.
+ */
+function declaredTools(declared) {
+  return declared.map((entry, i) => {
+    const where = `describe['tools'][${i}]`;
+    if (isMapping(entry)) {
+      const body = isMapping(entry.function) ? entry.function : entry;
+      for (const field of ["name", "description"]) {
+        const value = body[field] ?? null;
+        if (value !== null && typeof value !== "string") {
+          throw new ConfigurationError(
+            `${where}: '${field}' must be a string, got ${jsonType(value)}`);
+        }
+      }
+    }
+    const parsed = fromRequest(entry);
+    const tool = parsed === null ? null : fromWire(parsed);
+    if (tool === null) {
+      throw new ConfigurationError(
+        `${where} is not a tool: expected an OpenAI function spec, an ` +
+        `Anthropic tool, or a mapping with a 'name', got ${render(entry)}`);
+    }
+    const schema = parsed.input_schema;
+    if (schema !== null && schema !== undefined && !isMapping(schema)) {
+      throw new ConfigurationError(
+        `${where}: the schema must be a JSON-schema mapping, got ` +
+        jsonType(schema));
+    }
+    if (isMapping(entry.function) && Object.hasOwn(entry.function, "read_only")) {
+      throw new ConfigurationError(
+        `${where}: read_only goes beside 'function', not inside it`);
+    }
+    const readOnly = entry.read_only ?? null;
+    if (readOnly !== null && typeof readOnly !== "boolean") {
+      throw new ConfigurationError(
+        `${where}['read_only'] must be true or false, got ${render(readOnly)}`);
+    }
+    // OMITTED when undeclared, never null: the Python wire's absence rule.
+    return readOnly === null ? tool : { ...tool, read_only: readOnly };
+  });
+}
+
+/** The declared model, in the wire's model-config shape. */
+function declaredModel(declared) {
+  if (typeof declared === "string") {
+    if (!strip(declared)) {
+      throw new ConfigurationError("describe['model'] must not be empty");
+    }
+    return { provider: "unknown", model_name: declared };
+  }
+  const unknown = Object.keys(declared).filter((k) => !MODEL_KEYS.includes(k));
+  if (unknown.length) {
+    throw new ConfigurationError(
+      `describe['model'] got unknown key(s) ${keyList(unknown)}; it accepts ` +
+      keyList(MODEL_KEYS));
+  }
+  const name = declared.model_name ?? null;
+  const provider = declared.provider ?? null;
+  if (typeof name !== "string" || !strip(name)) {
+    throw new ConfigurationError("describe['model'] needs a 'model_name' string");
+  }
+  if (provider !== null && typeof provider !== "string") {
+    throw new ConfigurationError("describe['model']['provider'] must be a string");
+  }
+  const out = { provider: provider || "unknown", model_name: name };
+  const temperature = declaredTemperature(declared.temperature ?? null);
+  const maxTokens = declaredMaxTokens(declared.max_tokens ?? null);
+  if (temperature !== null) out.temperature = temperature;
+  if (maxTokens !== null) out.max_tokens = maxTokens;
+  return out;
+}
+
+/** A finite number, or null: `1e400` reads as Infinity, which is not JSON. */
+function declaredTemperature(value) {
+  if (value === null) return null;
+  if (typeof value !== "number") {
+    throw new ConfigurationError("describe['model']['temperature'] must be a number");
+  }
+  if (!Number.isFinite(value)) {
+    throw new ConfigurationError(
+      "describe['model']['temperature'] must be a finite number");
+  }
+  return value;
+}
+
+/** A whole number from 1 to 2**53 - 1, or null: past that, JSON reads round. */
+function declaredMaxTokens(value) {
+  if (value === null) return null;
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new ConfigurationError(
+      "describe['model']['max_tokens'] must be a whole number from 1 to " +
+      Number.MAX_SAFE_INTEGER);
+  }
+  return value;
+}
+
+/**
+ * `reflected` (a wire description) with the declared fields in place, the
+ * declaration alone when nothing was observed, or `reflected` unchanged when
+ * nothing was declared.
+ *
+ * `framework` names what the caller knows when nothing was observed. The
+ * Python SDK knows nothing about a custom agent and says `custom`; this plugin
+ * knows its host, and passes it.
+ *
+ * A part the declaration supplies stops being listed in `incomplete`: it is no
+ * longer unknown.
+ */
+export function applyDeclaration(
+  declared, { reflected = null, agentName, framework = "custom" },
+) {
+  if (declared === null || declared === undefined) return reflected;
+  const base = reflected ?? {
+    agent_name: agentName,
+    framework,
+    source_type: "sdk_runtime",
+    role: "standalone",
+    tool_definitions: null,
+  };
+  const out = { ...base, source_type: SOURCE_TYPE };
+  const supplied = new Set();
+  if (declared.system_prompt !== null) {
+    out.system_prompt = declared.system_prompt;
+    supplied.add("system_prompt");
+  }
+  if (declared.tools !== null) {
+    out.tool_definitions = declared.tools.map((t) => ({ ...t }));
+    supplied.add("tool_definitions").add("tool");
+  }
+  if (declared.model !== null) {
+    out.discovered_model_config = { ...declared.model };
+    supplied.add("discovered_model_config");
+  }
+  const incomplete = (Array.isArray(base.incomplete) ? base.incomplete : [])
+    .filter((part) => !supplied.has(part));
+  if (incomplete.length) out.incomplete = incomplete;
+  else delete out.incomplete;
+  return out;
+}

package/src/execution-identity.js

@@ -40,7 +40,8 @@ function freezeJsonTree(value, seen = new Set()) {
 }
 
 /** Unicode-code-point ordering, matching Python rather than UTF-16 sort. */
-function compareStrings(left, right) {
+/** Order by code point, as Python's `sorted()` orders `str`; not by UTF-16 unit. */
+export function compareStrings(left, right) {
   const a = [...left].map((c) => c.codePointAt(0));
   const b = [...right].map((c) => c.codePointAt(0));
   for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
@@ -442,3 +443,27 @@ export function createExecutionIdentityTracker({
     get refusal() { return normalized.reason; },
   };
 }
+
+/**
+ * `tracker` with every fingerprint withheld and its startup observation kept.
+ *
+ * For a DECLARED description (`describe`, see declaration.js): the declaration
+ * still merges over what was observed at startup, but it is the customer's
+ * word rather than an observation of what runs, so it anchors no execution
+ * identity -- not at registration, not on a rollout report, not on a
+ * production turn. The Python SDK withholds its digest the same way whenever
+ * `describe=` contributed.
+ */
+export function withholdFingerprints(tracker) {
+  return {
+    observe: () => null,
+    fingerprintFor: () => null,
+    consumeFingerprintFor: () => null,
+    get registrationFingerprint() { return null; },
+    get registrationDescription() { return tracker.registrationDescription; },
+    get enabled() { return false; },
+    get refusal() {
+      return "the description is declared with describe, not observed";
+    },
+  };
+}

package/src/index.js

@@ -84,12 +84,68 @@ import { conversationAccessGranted } from "./host.js";
 import {
   captureRoot, createTurnCapture, registerTurnCapture,
 } from "./capture.js";
-import { createExecutionIdentityTracker } from "./execution-identity.js";
+import {
+  createExecutionIdentityTracker, withholdFingerprints,
+} from "./execution-identity.js";
+import { resolveDeclaration } from "./declaration.js";
 
 export const PLUGIN_ID = "agent-flywheel";
 export const HOOK_NAME = "after_tool_call";
 export { DESCRIBE_HOOK_NAME };
 
+/**
+ * The operator's `describe`, validated -- or null, having said why.
+ *
+ * NOT A THROW, and that is the one place this differs from the Python SDK,
+ * which refuses to start on a bad declaration. Here a throw fails the plugin
+ * load and takes local capture down with it (see the mode fallback below), so
+ * a bad declaration is dropped with a warning that names the same cause
+ * Python's refusal names, and the agent registers what was observed.
+ *
+ * A STATIC declaration is checked whatever consent says, as Python checks it:
+ * lifting the opt-out later must not be the moment a typo surfaces. A
+ * FUNCTION runs only with consent -- nothing of the customer's runs for a
+ * description that will not be sent.
+ *
+ * Anything thrown is caught, not only a ConfigurationError: this runs inside
+ * `register()`, and the promise is that a declaration never costs the load.
+ */
+function declarationFor(config, logger) {
+  if (config.describe === null) return null;
+  const refusal = (err) => (err instanceof ConfigurationError
+    ? err.message
+    : `describe could not be read (${err?.message ?? typeof err})`);
+  if (!config.introspect) {
+    if (typeof config.describe !== "function") {
+      try {
+        resolveDeclaration(config.describe);
+      } catch (err) {
+        logger?.warn?.(
+          `[${PLUGIN_ID}] ${refusal(err)}. Fix ` +
+          `plugins.entries.${PLUGIN_ID}.config.describe before turning ` +
+          `introspection back on.`,
+        );
+      }
+    }
+    logger?.warn?.(
+      `[${PLUGIN_ID}] introspection is off (introspect / ` +
+      `PERCEPTEYE_INTROSPECT), and it wins: the description declared with ` +
+      `describe is not sent, and this agent registers no description at all.`,
+    );
+    return null;
+  }
+  try {
+    return resolveDeclaration(config.describe);
+  } catch (err) {
+    logger?.warn?.(
+      `[${PLUGIN_ID}] ${refusal(err)}. The declaration is ignored, so this ` +
+      `agent registers only what was observed. Fix ` +
+      `plugins.entries.${PLUGIN_ID}.config.describe.`,
+    );
+    return null;
+  }
+}
+
 
 export function register(api, pluginConfig = {}, env = process.env) {
   if (typeof api?.on !== "function") return null;
@@ -164,18 +220,44 @@ export function register(api, pluginConfig = {}, env = process.env) {
     );
     return null;
   }
-  const executionIdentity = createExecutionIdentityTracker({
-    executionSnapshot: config.executionSnapshot,
+  // What the operator says this agent is (see declaration.js), and whether
+  // they consented to saying anything at all.
+  const declaration = declarationFor(config, logger);
+  const tracker = createExecutionIdentityTracker({
+    // Refused discovery authors no identity: the Python SDK authors none when
+    // PERCEPTEYE_INTROSPECT is off. (The describer below may still write
+    // discovered_agent.json locally under PERCEPTEYE_TRAJECTORY_DIR; its one
+    // reader, the Python SDK's warm-up, asks consent itself.)
+    executionSnapshot: config.introspect ? config.executionSnapshot : null,
     mode: config.mode,
     agentId: config.agentId,
   });
-  if (config.executionSnapshot !== null && !executionIdentity.enabled) {
+  if (config.executionSnapshot !== null && !config.introspect) {
+    logger?.warn?.(
+      `[${PLUGIN_ID}] exact execution identity is disabled: introspection is ` +
+      `off (introspect / PERCEPTEYE_INTROSPECT), and identity is derived from ` +
+      `the description. Capture continues without an execution fingerprint.`,
+    );
+  } else if (config.executionSnapshot !== null && !tracker.enabled) {
     logger?.warn?.(
       `[${PLUGIN_ID}] exact execution identity is disabled: ` +
-      `${executionIdentity.refusal}. Capture continues without an affirmative ` +
+      `${tracker.refusal}. Capture continues without an affirmative ` +
       `execution fingerprint.`,
     );
   }
+  // A DECLARED description is the customer's word, not an observation: it
+  // merges over what was observed and anchors no fingerprint, anywhere.
+  const executionIdentity = declaration === null
+    ? tracker
+    : withholdFingerprints(tracker);
+  if (declaration !== null && tracker.enabled) {
+    // Said, because an operator who configured an execution snapshot and then
+    // added `describe` otherwise loses exact identity with no line anywhere.
+    logger?.warn?.(
+      `[${PLUGIN_ID}] exact execution identity is withheld: ` +
+      `${executionIdentity.refusal}. Remove describe to restore it.`,
+    );
+  }
   // ── WHERE TOOL CALLS LAND, decided by mode ────────────────────────────
   //
   // In TRAINING mode a trajectory belongs to one ROLLOUT, and the rollout
@@ -244,6 +326,7 @@ export function register(api, pluginConfig = {}, env = process.env) {
           )
           : null,
         executionIdentity,
+        declaration,
       });
     } catch (err) {
       logger?.warn?.(
@@ -272,7 +355,7 @@ export function register(api, pluginConfig = {}, env = process.env) {
     // inputs is a second answer that drifts the moment a cause is added.
     const conversationAccess = conversationAccessGranted(api, PLUGIN_ID);
     capture = registerTurnCapture(api, {
-      config, turns, pluginId: PLUGIN_ID, logger, env,
+      config, turns, pluginId: PLUGIN_ID, logger, env, declaration,
     });
     // THE LAST MILE. `capture` owns the one control-plane client, so this
     // reuses it rather than building a second against the same key -- and

package/src/rollout.js

@@ -88,6 +88,8 @@
  * at report time -- and when it is missing the operator gets one line naming
  * the exact setting, instead of a queue that quietly stops moving.
  */
+import { applyDeclaration } from "./declaration.js";
+import { FRAMEWORK } from "./describe.js";
 import { ConfigurationError, LeaseLost } from "./errors.js";
 import { isLowerSha256 } from "./execution-identity.js";
 import { conversationAccessGranted, lastAssistantText } from "./host.js";
@@ -670,6 +672,7 @@ export function createRolloutDriver({
  */
 export function registerRolloutDriver(api, {
   config, transport, pluginId, logger = null, executionIdentity = null,
+  declaration = null,
 }) {
   const verdict = driveVerdict(config, api, pluginId);
   if (!verdict.canDrive) {
@@ -702,13 +705,27 @@ export function registerRolloutDriver(api, {
     concurrency: 1,
     input_shape: "text",
     entrypoint: "openclaw-plugin",
-    // A startup observation is optional. When an adapter can provide one, the
-    // same immutable exact evidence drives both discovery and the execution
-    // digest registration sends before the first claim. Otherwise null says
-    // discovery ran but was unreadable; it never invents a worker identity.
-    discovered_agent: registrationDescription ?? null,
   };
-  if (isLowerSha256(registrationFingerprint?.execution_sha256)) {
+  // CONSENT, asked as the Python SDK's serve() asks it. Refused, the key is
+  // OMITTED, which the control plane records as the customer's opt-out
+  // (`disabled`). Given: a startup observation is optional -- when an adapter
+  // can provide one, the same immutable exact evidence drives both discovery
+  // and the execution digest registration sends before the first claim -- and
+  // what the operator declared (`describe`) wins over it where given. With
+  // neither, null says discovery ran but was unreadable; it never invents a
+  // worker identity, and a declaration never anchors one (index.js withholds
+  // the fingerprint).
+  const consented = config.introspect !== false;
+  if (consented) {
+    registrationSpec.discovered_agent = applyDeclaration(declaration, {
+      reflected: registrationDescription ?? null,
+      agentName: config.agentId,
+      // With nothing observed, the host is still known: this is OpenClaw.
+      framework: FRAMEWORK,
+    }) ?? null;
+  }
+  // The digest is derived from the description, so the same refusal covers it.
+  if (consented && isLowerSha256(registrationFingerprint?.execution_sha256)) {
     registrationSpec.agent_execution_sha256 =
       registrationFingerprint.execution_sha256;
   }