@percepteye/agent-flywheel 0.1.0

package/src/describe.js

@@ -0,0 +1,355 @@
+/**
+ * The agent describer: what this agent IS, observed from inside the host.
+ *
+ * WHY THIS EXISTS. The Python SDK discovers an agent by reflecting on a
+ * constructed object. That works for an in-process Python agent and cannot
+ * work for a CLI one: `fw.serve()` given a command entrypoint spawns an OS
+ * subprocess, so `runner.resolved` is None, `introspect(None)` returns None,
+ * and the control plane records `introspection_state = "unreadable"`. No tool
+ * catalogue means no generated workflows, which means no evaluation suites,
+ * no graded rollouts, and no dataset. The whole flywheel is downstream of this
+ * one fact, and reflection cannot cross a process AND a language boundary.
+ *
+ * WHY THIS HOOK. `llm_input` offers the post-policy provider/model and the
+ * assembled system prompt without exposing a mutation seam:
+ *
+ *   systemPrompt  the FULLY ASSEMBLED prompt -- the host's several prompt
+ *                 files, concatenated inside the Node process, from sources
+ *                 the Python SDK never opens.
+ *                 Reading those files ourselves would re-implement the host's
+ *                 assembly order and drift from it silently.
+ *   provider,model the model config, resolved after all overrides.
+ *
+ * IMPORTANT ABSENCE. OpenClaw's current PluginHookLlmInputEvent does NOT
+ * contain tools. Older code and tests invented that field and claimed an exact
+ * catalogue the real host could never supply. `buildRecord` still accepts an
+ * adapter-augmented `tools` array for forward compatibility, but the current
+ * host honestly writes `tool_definitions:null` plus an incomplete marker.
+ *
+ * WHY *THIS FILE* OBSERVES ONLY. The sibling recorder chose `after_tool_call`
+ * over `registerAgentToolResultMiddleware` on one rule: capturing evidence
+ * must never be able to change the behaviour being measured. `llm_input` keeps
+ * that rule. It is typed `(event, ctx) => Promise<void> | void` -- the same
+ * structurally non-mutating class as `after_tool_call`. The host discards our
+ * return value, so there is no seam here through which a description could
+ * alter a prompt, a tool result, or a routing decision. Introspection is a
+ * READ.
+ *
+ * THAT IS A CLAIM ABOUT THIS FILE, NOT ABOUT THE PACKAGE, and it used to read
+ * as both: "the mutation seams OpenClaw does expose -- `before_prompt_build`'s
+ * `{systemPrompt}`, `before_tool_call`'s `{block:true}` -- remain unused by
+ * this observer,
+ * deliberately." Half of that is no longer true. `policy.js` DOES use
+ * `before_prompt_build`, in production mode, to apply the system prompt the
+ * control plane approved -- and `before_model_resolve` plus a registered
+ * provider to point the agent at the model that prompt was certified with.
+ * Both deliberately, both gated on a pair check and a per-agent scope, both
+ * switchable off. Training mode now uses `before_tool_call` only as a lease
+ * revocation fence: after the control plane has requeued a rollout, later
+ * calls from the stale run are blocked from producing duplicate side effects.
+ * The describer is unaffected either way: a describer that could rewrite a
+ * prompt would be measuring its own output.
+ *
+ * The old wording also invited a wrong reading of that seam. `systemPrompt` is
+ * a field on the hook's RESULT, not on its EVENT: the event is
+ * `{prompt, messages}` and writing to it does nothing at all. `policy.js`
+ * carries the verified mechanics.
+ *
+ * THE ONE THING THIS HOOK COSTS. `llm_input` is a CONVERSATION hook
+ * (`CONVERSATION_HOOK_NAMES`, dist/hook-types-DQ9eTy2x.d.ts:386). The host
+ * REFUSES to register it for a non-bundled plugin unless the operator opts in
+ * with
+ * `plugins.entries.agent-flywheel.hooks.allowConversationAccess=true`
+ * (dist/registry-B8eQDFB4.js:4226-4241). That refusal is a warn-level
+ * diagnostic, not a throw, so a missing opt-in looks exactly like a working
+ * install that never fires. `register()` below says so out loud at startup
+ * rather than letting the operator discover it as an empty catalogue an hour
+ * later.
+ *
+ * ⚠ THAT GATE IS VERSION-SPECIFIC, verified by reading the INSTALLED OpenClaw
+ * 2026.7.1-2 -- the version `package.json`'s `openclaw.compat.pluginApi`
+ * requires. It is not universal: OpenClaw 2026.4.3 contains no
+ * `allowConversationAccess` and no `CONVERSATION_HOOK_NAMES` anywhere, so on
+ * that host `llm_input` is ungated and the setting the startup log asks for
+ * does not exist. Printing the line anyway is still right -- the failure it
+ * explains is otherwise silent, and a setting an older host ignores costs
+ * nothing -- but if the catalogue stays empty on a host where the opt-in is
+ * already set, this caveat is where to start: the cause is somewhere else and
+ * has not been found.
+ *
+ * Zero dependencies, `node:fs` only. This runs inside someone else's agent.
+ */
+import { renameSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { TRAJECTORY_DIR_ENV } from "./trajectory.js";
+
+export const DISCOVERED_AGENT_FILENAME = "discovered_agent.json";
+export const DESCRIBE_HOOK_NAME = "llm_input";
+
+/**
+ * `source_type` is a provenance claim, and it is NOT `sdk_runtime`.
+ *
+ * The Python probes mean something specific by `sdk_runtime`: the agent
+ * described itself by reflection over a constructed object. This description
+ * came from the HOST observing a real model call. Both are honest, they are
+ * not the same act, and only one of them can be wrong in the ways reflection
+ * is wrong. Naming it separately costs nothing -- the control plane stores
+ * `source_type` and has no reader for it, and the discovery consumer stamps
+ * its own source type when it builds its record rather than reading ours --
+ * and it means a future reader can tell the two apart without archaeology.
+ *
+ * Kept short on purpose: `flywheel_agents.source_type` is a varchar(64)
+ * written verbatim with no truncation, the exact column shape of a prior
+ * overflow that refused 100% of inserts.
+ */
+export const SOURCE_TYPE = "openclaw_llm_input";
+
+/**
+ * `framework` is a LOOKUP KEY, not a label.
+ *
+ * The discovery consumer maps exactly `"openclaw"` to its OpenClaw
+ * framework. Any other spelling -- `open_claw`,
+ * `openclaw-cli`, the agent's own name -- silently degrades to
+ * an UNKNOWN framework, which is logged and tolerated and loses the framework
+ * identity in every generated workflow's provenance. Same varchar(64).
+ */
+export const FRAMEWORK = "openclaw";
+
+/**
+ * Postgres JSONB cannot store a NUL byte or a lone surrogate in any string:
+ * it raises `unsupported Unicode escape sequence`, which surfaces as an
+ * uncaught 500 on registration, 100% of the time, for that agent.
+ *
+ * This matters here specifically because the payload is not ours. The system
+ * prompt is a concatenation of customer-authored markdown files, and an
+ * adapter-augmented tool array is arbitrary provider-shaped JSON. A
+ * description that cannot be stored is worth less than one missing a field,
+ * so we scrub rather than let the registration fail.
+ */
+function scrub(value) {
+  if (typeof value !== "string") return value;
+  // eslint-disable-next-line no-control-regex
+  return value.replace(/\u0000/g, "").replace(/[\uD800-\uDFFF]/g, (ch, i, s) => {
+    const code = ch.charCodeAt(0);
+    const isHigh = code <= 0xdbff;
+    const partner = isHigh ? s.charCodeAt(i + 1) : s.charCodeAt(i - 1);
+    const paired = isHigh
+      ? partner >= 0xdc00 && partner <= 0xdfff
+      : partner >= 0xd800 && partner <= 0xdbff;
+    return paired ? ch : "";
+  });
+}
+
+/** Recursively scrub every string in a JSON-ish value. */
+function scrubDeep(value) {
+  if (typeof value === "string") return scrub(value);
+  if (Array.isArray(value)) return value.map(scrubDeep);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[scrub(k)] = scrubDeep(v);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Normalise ONE host tool object into the discovery protocol's tool shape.
+ *
+ * This is the load-bearing translation, and it is load-bearing because the
+ * consumer is exact and silent. The consumer reads `input_schema` and NOTHING else: it does not accept the
+ * host's native
+ * `parameters` key, and it does not unwrap the OpenAI
+ * `{type:"function", function:{...}}` envelope. Both failures are silent and
+ * differently shaped -- `parameters` yields a tool with an EMPTY schema,
+ * while the OpenAI envelope yields a tool with NO NAME, which the consumer
+ * then drops entirely. Forward `event.tools` verbatim and the launch gate still
+ * opens (the list is truthy) while the catalogue is empty or nameless.
+ *
+ * An optional adapter may supply any of these common shapes, so handle all
+ * three rather than betting on one provider envelope.
+ *
+ * @returns {{name:string,description:string,input_schema:object,original_format:string}|null}
+ */
+export function normalizeTool(raw) {
+  if (!raw || typeof raw !== "object") return null;
+
+  // The OpenAI function-calling envelope: the real tool is one level down.
+  const isEnvelope =
+    raw.type === "function" && raw.function && typeof raw.function === "object";
+  const t = isEnvelope ? raw.function : raw;
+
+  const name = typeof t.name === "string" ? t.name.trim() : "";
+  // The consumer drops a nameless tool anyway; dropping it here means the count we
+  // report is the count that survives, so "7 tools" never means "7 sent, 3
+  // arrived".
+  if (!name) return null;
+
+  const schema =
+    t.input_schema ?? t.inputSchema ?? t.parameters ?? t.schema ?? null;
+
+  return {
+    name: scrub(name),
+    description: scrub(
+      typeof t.description === "string" ? t.description
+        : typeof t.label === "string" ? t.label
+          : "",
+    ),
+    // `{type:"object",properties:{}}` is what the consumer substitutes for a falsy
+    // schema. Emitting it here keeps the wire record self-describing rather
+    // than relying on a default two repos away.
+    input_schema:
+      schema && typeof schema === "object"
+        ? scrubDeep(schema)
+        : { type: "object", properties: {} },
+    original_format: isEnvelope ? "openai_function" : "openclaw_tool",
+  };
+}
+
+/** Normalise the host's tool array. `undefined` in means `null` out. */
+export function normalizeTools(rawTools) {
+  // THE ABSENCE CONTRACT, preserved across the process boundary. `null` means
+  // we could not look; `[]` means we looked and the agent has no tools. The
+  // consumer stamps a `not observed` marker on the first and grades on the
+  // difference, and the control plane's launch gate refuses a run whose agent
+  // reports zero tools. Collapsing these two into `[]` would turn "we did not
+  // observe" into a confident claim that the agent can do nothing.
+  if (!Array.isArray(rawTools)) return null;
+  const out = [];
+  for (const raw of rawTools) {
+    const tool = normalizeTool(raw);
+    if (tool) out.push(tool);
+  }
+  return out;
+}
+
+/**
+ * Build the wire record from one `llm_input` event.
+ *
+ * Field-for-field the shape of `DiscoveredAgent.to_wire()` in the Python SDK,
+ * because that is what the control plane stores and reads. The two
+ * are one ABI; this is the Node end of it, exactly as `trajectory.js` is the
+ * Node end of the tool-outcome ABI.
+ */
+export function buildRecord(event, ctx = {}) {
+  const tools = normalizeTools(event?.tools);
+  const record = {
+    agent_name: scrub(String(ctx.agentId || event?.sessionId || "openclaw-agent")),
+    framework: FRAMEWORK,
+    source_type: SOURCE_TYPE,
+    role: "standalone",
+    tool_definitions: tools,
+  };
+
+  if (typeof event?.systemPrompt === "string" && event.systemPrompt) {
+    record.system_prompt = scrub(event.systemPrompt);
+  }
+  if (event?.provider || event?.model) {
+    record.discovered_model_config = {
+      provider: scrub(String(event.provider || "unknown")),
+      model_name: scrub(String(event.model || "unknown")),
+    };
+  }
+
+  // `incomplete` names the parts we could not read, so a consumer can tell a
+  // gap from an absence. The host declares `systemPrompt` and `tools`
+  // optional, so either can genuinely be missing from a real event.
+  const incomplete = [];
+  if (!record.system_prompt) incomplete.push("system_prompt");
+  if (tools === null) incomplete.push("tool_definitions");
+  if (incomplete.length) record.incomplete = incomplete;
+
+  return record;
+}
+
+/**
+ * A describer bound to a directory, or an inert one when none is set.
+ *
+ * WRITE POLICY. `llm_input` fires at each host run's assembled model boundary.
+ * If a host adapter supplies tools, its universe may vary across runs: a
+ * sub-agent turn can carry a subset. So we keep the richest catalogue rather than the
+ * newest -- last-write-wins would let a narrow sub-agent turn overwrite the
+ * agent's real catalogue with a fraction of it, and the result would look
+ * perfectly healthy at every layer downstream.
+ *
+ * The first event always writes, so an agent that genuinely has no tools
+ * still produces a file and still reaches `described`.
+ */
+export function createDescriber({ dir = null, onError = null } = {}) {
+  let best = -1;
+  let warned = false;
+
+  const resolveDir = () => dir ?? process.env[TRAJECTORY_DIR_ENV] ?? null;
+
+  return {
+    get active() {
+      return Boolean(resolveDir());
+    },
+    /** @returns {boolean} whether this event was written. */
+    handle(event, ctx = {}) {
+      const base = resolveDir();
+      if (!base) return false;
+
+      const record = buildRecord(event, ctx);
+      const count = record.tool_definitions?.length ?? 0;
+      if (best >= 0 && count <= best) return false;
+
+      const path = join(base, DISCOVERED_AGENT_FILENAME);
+      const tmp = `${path}.${process.pid}.tmp`;
+      try {
+        mkdirSync(base, { recursive: true });
+        // Write-then-rename. The Python SDK POLLS for this file while the
+        // warm-up child runs, so a reader can arrive mid-write; rename is
+        // atomic within a filesystem, so the reader sees either no file or a
+        // complete one, never half a JSON object.
+        writeFileSync(tmp, JSON.stringify(record), "utf8");
+        renameSync(tmp, path);
+        best = count;
+        return true;
+      } catch (err) {
+        // Never fail an agent over telemetry. Report once, then stay quiet.
+        if (!warned) {
+          warned = true;
+          if (onError) onError(err);
+        }
+        return false;
+      }
+    },
+  };
+}
+
+/**
+ * Register the describer on an OpenClaw plugin api.
+ *
+ * Returns the describer, or null when the host has no `on()`. The
+ * conversation-access opt-in cannot be checked from here -- the host's
+ * refusal is a diagnostic on ITS side and our handler simply never fires --
+ * so the caller warns at startup instead.
+ */
+export function registerDescriber(api, { logger = null, onObservation = null } = {}) {
+  if (typeof api?.on !== "function") return null;
+
+  const describer = createDescriber({
+    onError: (err) => logger?.warn?.(
+      `[agent-flywheel] agent description write failed; this agent ` +
+      `will register as introspection_state=unreadable and no workflows will ` +
+      `be generated for it: ${err?.message ?? err}`,
+    ),
+  });
+
+  api.on(DESCRIBE_HOOK_NAME, (event, ctx) => {
+    try {
+      onObservation?.(event, ctx ?? {});
+    } catch {
+      // Identity is an independent projection. It may abstain without costing
+      // the advisory description written below.
+    }
+    try {
+      describer.handle(event, ctx ?? {});
+    } catch {
+      /* one lost description is not worth an interrupted agent */
+    }
+  });
+
+  return describer;
+}

package/src/dsh-classify.js

@@ -0,0 +1,110 @@
+/**
+ * Turning a DeepSeek Harness `tools/result` outcome into a flywheel outcome.
+ *
+ * dsh types its result as a discriminated union on `isError`, which is a real
+ * discriminant rather than an optional flag — so `isError: true` is a positive
+ * assertion of failure and can simply be believed.
+ *
+ * `isError: false` is the interesting half, and it does NOT mean success. The
+ * bash tool renders a failing exit as TEXT (`[exit code: 3]`) appended to the
+ * model-facing content and still settles as a non-error result: the tool call
+ * worked, the command did not. Reading the flag alone scores a failed command
+ * as a win — the same trap OpenClaw sets with `status: "completed"`.
+ *
+ * What makes dsh better to classify is that its exec tools declare a real
+ * output schema: `exitCode`, `signal`, `timedOut`, `aborted`, and a `kind`
+ * discriminating foreground from background. That is enough to be honest about
+ * three cases a cruder reading collapses into one.
+ */
+import { readExit } from "./classify.js";
+
+/** dsh's exec tools, by their registered names. */
+export const DSH_EXEC_TOOLS = new Set(["bash", "pwsh"]);
+
+/**
+ * Tools whose silence really is success: no in-band status channel, so a
+ * failure has nowhere to go but `isError`. These are dsh's own registered
+ * names. Anything absent from both sets grades `unknown` until a fixture
+ * earns it a place.
+ */
+export const DSH_VERDICT_TOOLS = new Set([
+  "read", "write", "edit", "read_image", "str_replace_editor", "todo_write",
+]);
+
+/**
+ * @param {string} name    the registered tool name
+ * @param {{isError?: boolean, value?: unknown, error?: {message?: string, info?: unknown}}} result
+ * @returns {{outcome:"ok"|"failed"|"unknown", status_code:null,
+ *            error?:string, error_class?:string}}
+ */
+export function classifyDsh(name, result) {
+  const r = result && typeof result === "object" ? result : {};
+
+  // A positive assertion by the harness that the call failed.
+  if (r.isError === true) {
+    const failure = r.error && typeof r.error === "object" ? r.error : {};
+    const info = failure.info;
+    return {
+      outcome: "failed",
+      status_code: null,
+      error: typeof failure.message === "string"
+        ? failure.message.slice(0, 1000)
+        : undefined,
+      // dsh carries an internal error class on `info`; it is far more useful
+      // downstream than a generic label when it is a plain string.
+      error_class: typeof info === "string" ? info
+        : (info && typeof info === "object" && typeof info.code === "string")
+          ? info.code
+          : "ToolError",
+    };
+  }
+
+  // `isError` absent is not `isError: false`. The harness did not say.
+  if (r.isError !== false) return { outcome: "unknown", status_code: null };
+
+  const value = r.value;
+  const v = value && typeof value === "object" ? value : {};
+
+  if (DSH_EXEC_TOOLS.has(name)) {
+    // A backgrounded command has been LAUNCHED, not completed. There is no
+    // exit code because nothing has exited. Grading it `ok` would claim a
+    // result for work still running.
+    if (v.kind === "background") {
+      return { outcome: "unknown", status_code: null,
+               error_class: "StillRunning" };
+    }
+    // Cancelled by the caller. The command did not get to say what it would
+    // have done, and that is not the agent making a mistake.
+    if (v.aborted === true) {
+      return { outcome: "unknown", status_code: null, error_class: "Aborted" };
+    }
+    if (v.timedOut === true) {
+      return { outcome: "failed", status_code: null, error_class: "TimedOut" };
+    }
+    // Killed by a signal: `exitCode` is null precisely here, so this must be
+    // checked before treating a null exit as unreadable.
+    if (typeof v.signal === "string" && v.signal) {
+      return { outcome: "failed", status_code: null,
+               error_class: `Signal:${v.signal}` };
+    }
+    const exit = readExit(value);
+    if (exit === undefined) {
+      // We did not observe the verdict. Falling back to `ok` here is the
+      // rounding-up this module exists to prevent.
+      return { outcome: "unknown", status_code: null,
+               error_class: "ExitStatusUnreadable" };
+    }
+    if (exit === 0) return { outcome: "ok", status_code: null };
+    // An exit code is not an HTTP status; putting 127 in `status_code` would
+    // fail the contract's 100..599 check and would be a lie besides.
+    return { outcome: "failed", status_code: null,
+             error_class: `ExitStatus:${exit}` };
+  }
+
+  if (DSH_VERDICT_TOOLS.has(name)) return { outcome: "ok", status_code: null };
+
+  // Everything unproven: web tools, terminal session tools, subagent tools,
+  // and every tool a plugin registered. A tool that reports its own failure
+  // inside a successful-looking value is invisible from here.
+  return { outcome: "unknown", status_code: null };
+}

package/src/dsh.js

@@ -0,0 +1,130 @@
+/**
+ * agent-flywheel — a DeepSeek Harness (Cordis) plugin.
+ *
+ * Records tool-call outcomes into the active rollout's trajectory. Observes
+ * only, and here that is guaranteed by the harness rather than merely intended.
+ *
+ * WHY `tools/result`. dsh's tool pipeline exposes several seams, and most of
+ * them are waterfalls: `tools/execute` wraps dispatch, `tools/post` can accept,
+ * replace or BLOCK a result, and `tools/code-dispatch-log` rewrites what gets
+ * logged. A listener on any of those can change what the model sees.
+ *
+ * `tools/result` is declared `@mode emit` and typed to return `undefined`. Its
+ * documentation is explicit — "Observe the frozen, lossless-JSON final outcome.
+ * Listener failures are contained." — and the registry DEEP-FREEZES both the
+ * execution and the result before publishing them, with an invariant that
+ * fails the harness if it ever publishes something unfrozen. So this plugin
+ * cannot alter a tool result even by accident: there is no return channel, and
+ * the object it receives is immutable.
+ *
+ * That is the same rule the OpenClaw plugin follows for the same reason:
+ * capturing evidence must never be able to change the behaviour being
+ * measured. dsh simply enforces it harder.
+ *
+ * THIS LANE HAS NO ROLLOUT DRIVER, in any mode. The OpenClaw lane can claim a
+ * rollout and deliver its task into the agent's next turn (see `rollout.js`,
+ * training mode only); Cordis exposes no equivalent seam, so on dsh this
+ * plugin observes and nothing else regardless of `PERCEPTEYE_AGENT_MODE`. Said
+ * here because the README's mode table describes the package, and a reader who
+ * takes it to mean "dsh claims rollouts too" would wait for trajectories that
+ * are never going to arrive.
+ *
+ * Zero dependencies. `ctx` is supplied by the harness; nothing is imported
+ * from it, so this module loads even when dsh is absent — which is what lets
+ * one package serve two harnesses.
+ */
+import { classifyDsh } from "./dsh-classify.js";
+import { extractEntityIds } from "./evidence.js";
+import { createWriter, toWire, TRAJECTORY_DIR_ENV } from "./trajectory.js";
+
+/** Display metadata; labels the plugin in Cordis diagnostics. */
+export const name = "agent-flywheel";
+
+export const HOOK_NAME = "tools/result";
+
+/** The agent that made the call, or undefined when nothing names one. */
+function agentName(exec) {
+  const agent = exec && typeof exec === "object" ? exec.agent : undefined;
+  if (!agent || typeof agent !== "object") return undefined;
+  for (const key of ["name", "id"]) {
+    const v = agent[key];
+    if (typeof v === "string" && v.trim()) return v;
+  }
+  return undefined;
+}
+
+/**
+ * Build the trajectory record for one settled execution.
+ *
+ * Exported for tests: the harness supplies frozen objects, and a recorder that
+ * can only be exercised through a live agent loop is a recorder nobody checks.
+ */
+export function recordFor(exec, result) {
+  const toolName = typeof exec?.name === "string" ? exec.name : null;
+  if (!toolName) return null;
+
+  const verdict = classifyDsh(toolName, result);
+  return toWire({
+    name: toolName,
+    // dsh types `arguments` as `unknown` but guarantees it is losslessly
+    // JSON-serializable. A non-object stays out rather than being coerced
+    // into a shape it never had.
+    args: exec.arguments && typeof exec.arguments === "object"
+      ? exec.arguments
+      : {},
+    outcome: verdict.outcome,
+    status_code: null,
+    error: verdict.error,
+    error_class: verdict.error_class,
+    agent_name: agentName(exec),
+    // `callId` is the model's own id for a root call. A nested call under code
+    // mode gets a registry-assigned one, which is still the only identifier
+    // that execution has.
+    tool_call_id: typeof exec.callId === "string" ? exec.callId : undefined,
+    // Resolved from the canonical value, which dsh documents as
+    // "execution-local ... deliberately omitted from durable events" -- so it
+    // is available HERE and nowhere later. Identity is taken and the value
+    // itself is dropped.
+    entity_ids: extractEntityIds(result?.value),
+  });
+}
+
+/**
+ * Cordis plugin entry. Named `apply`, per the plugin contract.
+ *
+ * Deliberately no `default` export in this module: the Cordis loader
+ * normalizes with `exports.default ?? exports`, so a default here would be
+ * handed to the harness INSTEAD of `apply` and the plugin would fail to load.
+ * The OpenClaw entry, which does export a default, is a separate module for
+ * exactly that reason.
+ */
+export function apply(ctx) {
+  if (!ctx || typeof ctx.on !== "function") return null;
+
+  const logger = ctx.logger ?? null;
+  const writer = createWriter({
+    onError: (err) => logger?.warn?.(
+      `[${name}] trajectory write failed; tool outcomes are not being ` +
+      `recorded for this run: ${err?.message ?? err}`,
+    ),
+  });
+
+  const dispose = ctx.on(HOOK_NAME, (exec, result) => {
+    // dsh contains listener failures already, but it logs each one. Swallowing
+    // here keeps a malformed execution from filling a customer's diagnostics
+    // with our name: one lost record, never a failed run, never a noisy one.
+    try {
+      const record = recordFor(exec, result);
+      if (record) writer.write(record);
+    } catch {
+      /* one lost record is not worth an interrupted agent */
+    }
+    // `@mode emit` listeners return undefined. Returning anything else here
+    // would be meaningless at best.
+    return undefined;
+  });
+
+  return { writer, dispose };
+}
+
+export { TRAJECTORY_DIR_ENV };

package/src/errors.js

@@ -0,0 +1,37 @@
+/**
+ * The two failures a caller must be able to tell apart.
+ *
+ * `LeaseLost` is not an error in the operational sense -- it is the control
+ * plane saying "this rollout is no longer yours", which happens whenever a
+ * lease lapses and the work is requeued. A caller that treats it as a
+ * transport failure retries forever against a rollout someone else now owns.
+ */
+export class TransportError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TransportError";
+  }
+}
+
+export class LeaseLost extends TransportError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "LeaseLost";
+  }
+}
+
+/**
+ * A setting this package refuses to guess at.
+ *
+ * Raised for an unrecognised `PERCEPTEYE_AGENT_MODE`, and only there. The
+ * alternative -- defaulting a typo to `training` -- keeps a process
+ * contributing rollouts on a customer's credentials after an operator
+ * believed they had switched it off, with nothing printed anywhere. There is
+ * no safe guess for a mode, so a bad one is a startup failure.
+ */
+export class ConfigurationError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ConfigurationError";
+  }
+}