@senpi/runtime 1.1.0-dev.runtime-phase-2.20260521133839 → 1.1.0-dev.runtime-phase-2.20260522115501

package/dist/runtime/decision-errors.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Classification of LLM-decision failures into user-facing messages + a retry flag.
+ *
+ * ## Why this module exists
+ *
+ * When an action runs an LLM decision (`OpenClawLlmDecision.decide`,
+ * `src/actions/llm-decision/openclaw-llm-decision.ts`) and the OpenClaw `llm-task`
+ * tool fails, the only thing the runtime has is a flat error string. Two consumers
+ * need to make decisions from that string:
+ *
+ *   1. The **notification layer** ({@link formatDecisionErrorNotification} in
+ *      `notifications.ts`) — what to tell the skill author in Telegram.
+ *   2. The **decision client** (`openclaw-llm-decision.ts`) — whether a retry can
+ *      plausibly succeed.
+ *
+ * ## Three pieces, separated on purpose
+ *
+ *   1. {@link DECISION_ERROR_MESSAGES} — a **flat catalog** of every user-facing
+ *      string, keyed by {@link DecisionErrorCode}. This is the single place to read,
+ *      review, or edit copy. Templates use `{placeholder}` tokens.
+ *   2. {@link DECISION_ERROR_TABLE} — the ordered matchers (raw string → code) and
+ *      the `retryable` flag, plus the per-code logic that produces template values.
+ *   3. {@link classifyDecisionError} — walks the table, renders the catalog entry.
+ *
+ * To change wording: edit {@link DECISION_ERROR_MESSAGES} only. To change matching
+ * or retry behavior: edit {@link DECISION_ERROR_TABLE} only.
+ *
+ * ## Where the raw strings come from
+ *
+ * The granular OpenClaw messages (e.g. `"LLM returned empty output"`,
+ * `"prompt required"`) are thrown by the **external gateway**, not by this plugin.
+ * They reach us **embedded** inside one of the wrappers that
+ * `OpenClawLlmDecision.decide` throws:
+ *
+ *   - `OpenClaw gateway error (<status>): <body-text>`   (non-2xx HTTP)
+ *   - `OpenClaw gateway rejected request: <body.error>`  (HTTP 200, `body.ok === false`)
+ *
+ * Matchers therefore look for the granular substring **anywhere** in the string,
+ * not anchored. Our own parse failures (`Invalid llm-task response: ...` from
+ * `extractDecision`) are classified too.
+ *
+ * ## v2026.2.22 caveat
+ *
+ * On OpenClaw v2026.2.22 (current prod) the gateway collapses most `llm-task`
+ * failures into a generic `tool_error` whose message is `"tool execution failed"`,
+ * so the granular substrings frequently do **not** surface there — only on
+ * v2026.5.7+. The table is built in full anyway: on v2026.2.22 the generic
+ * `tool_error` matches {@link DecisionErrorCode.ProviderError}; on newer gateways
+ * the specific code matches.
+ */
+/** Stable identifier for each classified LLM-decision failure mode. */
+export declare enum DecisionErrorCode {
+    /** Gateway auth token missing in env/config — thrown before any HTTP call. */
+    GatewayTokenMissing = "GATEWAY_TOKEN_MISSING",
+    /** `fetch()` rejected before a response (connection refused/reset/DNS). */
+    GatewayUnreachable = "GATEWAY_UNREACHABLE",
+    /** Gateway returned 404 — plugin not installed at this path / version mismatch. */
+    PluginEndpointMissing = "PLUGIN_ENDPOINT_MISSING",
+    /** `llm-task` invoked with empty/whitespace prompt — missing `decision_prompt`. */
+    PromptRequired = "PROMPT_REQUIRED",
+    /** `decision_model` did not resolve to a known provider/model pair. */
+    ProviderModelUnresolved = "PROVIDER_MODEL_UNRESOLVED",
+    /** Resolved model is not on the gateway's `allowedModels` allowlist. */
+    ModelNotAllowed = "MODEL_NOT_ALLOWED",
+    /** Context/payload passed to `llm-task` was not JSON-serializable — internal bug. */
+    InputNotSerializable = "INPUT_NOT_SERIALIZABLE",
+    /** Provider responded but produced no text (safety filter / refusal / empty completion). */
+    LlmEmptyOutput = "LLM_EMPTY_OUTPUT",
+    /** Model reply could not be parsed as JSON (truncation / prose around JSON). */
+    LlmInvalidJson = "LLM_INVALID_JSON",
+    /** Model reply was valid JSON but failed schema validation. */
+    LlmSchemaMismatch = "LLM_SCHEMA_MISMATCH",
+    /** Upstream provider error (rate limit / outage) or generic `tool_error`. */
+    ProviderError = "PROVIDER_ERROR",
+    /** Gateway/upstream timeout (408/504) or runtime-side abort — we already waited 90s. */
+    Timeout = "TIMEOUT",
+    /** Embedded LLM helper failed to load on the host — corrupt/partial OpenClaw install. */
+    EmbeddedAgentUnavailable = "EMBEDDED_AGENT_UNAVAILABLE",
+    /** Thinking level string does not normalize to any known level (v2026.5.7+). */
+    InvalidThinkingLevel = "INVALID_THINKING_LEVEL",
+    /** Thinking level is known but unsupported by the resolved model (v2026.5.7+). */
+    ThinkingLevelUnsupported = "THINKING_LEVEL_UNSUPPORTED",
+    /** Gateway returned 200 with a response shape this plugin can't parse — internal bug. */
+    PluginResponseShape = "PLUGIN_RESPONSE_SHAPE",
+    /** Any other 5xx with no recognizable structured body. */
+    OpenClawUnexpected = "OPENCLAW_UNEXPECTED",
+    /** No matcher matched — surfaces the raw message so operators can still diagnose. */
+    Unknown = "UNKNOWN"
+}
+/**
+ * The single catalog of every user-facing message, keyed by {@link DecisionErrorCode}.
+ *
+ * Templates use `{token}` placeholders, filled by the matching entry's `vars`
+ * function in {@link DECISION_ERROR_TABLE} (e.g. `{name}` = action name, `{model}`,
+ * `{list}`, `{errors}`, `{level}`, `{hint}`, `{providerModel}`, `{raw}`). A `{token}`
+ * with no supplied value is left verbatim so a missing var is visible, not silent.
+ *
+ * **This is the only place to edit copy.** Nothing else hardcodes a message.
+ */
+export declare const DECISION_ERROR_MESSAGES: Record<DecisionErrorCode, string>;
+/**
+ * Plugin-side context the gateway error string does not carry but the message
+ * needs (e.g. the action's YAML name, the configured `decision_model`).
+ */
+export interface DecisionErrorContext {
+    /** The failing action's `name` from the runtime YAML (the `{name}` placeholder). */
+    actionName?: string;
+    /** The action's configured `decision_model` (fallback for the `{model}` placeholder). */
+    model?: string;
+}
+/** Result of classifying a raw LLM-decision error string. */
+export interface ClassifiedDecisionError {
+    code: DecisionErrorCode;
+    /** Whether a retry of the `llm-task` call can plausibly succeed. */
+    retryable: boolean;
+    /** User-facing message for Telegram. */
+    userMessage: string;
+}
+/** One row of {@link DECISION_ERROR_TABLE}. */
+interface DecisionErrorEntry {
+    code: DecisionErrorCode;
+    /**
+     * Tested against the raw error string. Returning a {@link RegExpMatchArray}
+     * (truthy) or `true` counts as a match; `null`/`false` means no match. Capture
+     * groups are forwarded to {@link DecisionErrorEntry.vars} as `caps`.
+     */
+    match: (raw: string) => RegExpMatchArray | boolean | null;
+    retryable: boolean;
+    /**
+     * Optional: produces the `{token}` substitutions for this code's catalog entry.
+     * Omit for static messages.
+     * @param caps - Capture groups from {@link DecisionErrorEntry.match}, or `null`.
+     * @param ctx - Plugin-side context (action name, configured model).
+     * @param raw - The original raw error string.
+     */
+    vars?: (caps: RegExpMatchArray | null, ctx: DecisionErrorContext, raw: string) => Record<string, string>;
+}
+/**
+ * Ordered classification table — matchers + retry flag + template-variable logic.
+ * First match wins, so keep specific matchers above generic ones (e.g.
+ * `LlmEmptyOutput` before the catch-all `ProviderError`, since both can appear
+ * inside a `"rejected request: ..."` wrapper). Copy lives in
+ * {@link DECISION_ERROR_MESSAGES}, not here.
+ */
+export declare const DECISION_ERROR_TABLE: readonly DecisionErrorEntry[];
+/**
+ * Classify a raw LLM-decision error string into a {@link ClassifiedDecisionError}.
+ *
+ * Walks {@link DECISION_ERROR_TABLE} in order; the first matching entry wins. If
+ * nothing matches, returns {@link DecisionErrorCode.Unknown} (not retryable). The
+ * message is always rendered from {@link DECISION_ERROR_MESSAGES}.
+ *
+ * @param rawMessage - The error string thrown by the decision client (may embed an
+ *   OpenClaw gateway message). Non-string / empty inputs are coerced safely.
+ * @param ctx - Optional plugin-side context for placeholders the gateway can't supply.
+ */
+export declare function classifyDecisionError(rawMessage: string, ctx?: DecisionErrorContext): ClassifiedDecisionError;
+/**
+ * Convenience predicate for retry wiring: `true` when a retry of the failed
+ * `llm-task` call can plausibly succeed.
+ *
+ * @param error - The thrown error (or any value); only its message is inspected.
+ */
+export declare function isRetryableDecisionError(error: unknown): boolean;
+export {};
+//# sourceMappingURL=decision-errors.d.ts.map

package/dist/runtime/decision-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-errors.d.ts","sourceRoot":"","sources":["../../src/runtime/decision-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,uEAAuE;AACvE,oBAAY,iBAAiB;IAC3B,8EAA8E;IAC9E,mBAAmB,0BAA0B;IAC7C,2EAA2E;IAC3E,kBAAkB,wBAAwB;IAC1C,mFAAmF;IACnF,qBAAqB,4BAA4B;IACjD,mFAAmF;IACnF,cAAc,oBAAoB;IAClC,uEAAuE;IACvE,uBAAuB,8BAA8B;IACrD,wEAAwE;IACxE,eAAe,sBAAsB;IACrC,qFAAqF;IACrF,oBAAoB,2BAA2B;IAC/C,4FAA4F;IAC5F,cAAc,qBAAqB;IACnC,gFAAgF;IAChF,cAAc,qBAAqB;IACnC,+DAA+D;IAC/D,iBAAiB,wBAAwB;IACzC,6EAA6E;IAC7E,aAAa,mBAAmB;IAChC,wFAAwF;IACxF,OAAO,YAAY;IACnB,yFAAyF;IACzF,wBAAwB,+BAA+B;IACvD,gFAAgF;IAChF,oBAAoB,2BAA2B;IAC/C,kFAAkF;IAClF,wBAAwB,+BAA+B;IACvD,yFAAyF;IACzF,mBAAmB,0BAA0B;IAC7C,0DAA0D;IAC1D,kBAAkB,wBAAwB;IAC1C,qFAAqF;IACrF,OAAO,YAAY;CACpB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAgFrE,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6DAA6D;AAC7D,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,iBAAiB,CAAC;IACxB,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;IACnB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+CAA+C;AAC/C,UAAU,kBAAkB;IAC1B,IAAI,EAAE,iBAAiB,CAAC;IACxB;;;;OAIG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,gBAAgB,GAAG,OAAO,GAAG,IAAI,CAAC;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,CACL,IAAI,EAAE,gBAAgB,GAAG,IAAI,EAC7B,GAAG,EAAE,oBAAoB,EACzB,GAAG,EAAE,MAAM,KACR,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAeD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,kBAAkB,EA+HpD,CAAC;AAEX;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,oBAAyB,GAC7B,uBAAuB,CAoBzB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGhE"}

package/dist/runtime/decision-errors.js

@@ -0,0 +1,328 @@
+/**
+ * Classification of LLM-decision failures into user-facing messages + a retry flag.
+ *
+ * ## Why this module exists
+ *
+ * When an action runs an LLM decision (`OpenClawLlmDecision.decide`,
+ * `src/actions/llm-decision/openclaw-llm-decision.ts`) and the OpenClaw `llm-task`
+ * tool fails, the only thing the runtime has is a flat error string. Two consumers
+ * need to make decisions from that string:
+ *
+ *   1. The **notification layer** ({@link formatDecisionErrorNotification} in
+ *      `notifications.ts`) — what to tell the skill author in Telegram.
+ *   2. The **decision client** (`openclaw-llm-decision.ts`) — whether a retry can
+ *      plausibly succeed.
+ *
+ * ## Three pieces, separated on purpose
+ *
+ *   1. {@link DECISION_ERROR_MESSAGES} — a **flat catalog** of every user-facing
+ *      string, keyed by {@link DecisionErrorCode}. This is the single place to read,
+ *      review, or edit copy. Templates use `{placeholder}` tokens.
+ *   2. {@link DECISION_ERROR_TABLE} — the ordered matchers (raw string → code) and
+ *      the `retryable` flag, plus the per-code logic that produces template values.
+ *   3. {@link classifyDecisionError} — walks the table, renders the catalog entry.
+ *
+ * To change wording: edit {@link DECISION_ERROR_MESSAGES} only. To change matching
+ * or retry behavior: edit {@link DECISION_ERROR_TABLE} only.
+ *
+ * ## Where the raw strings come from
+ *
+ * The granular OpenClaw messages (e.g. `"LLM returned empty output"`,
+ * `"prompt required"`) are thrown by the **external gateway**, not by this plugin.
+ * They reach us **embedded** inside one of the wrappers that
+ * `OpenClawLlmDecision.decide` throws:
+ *
+ *   - `OpenClaw gateway error (<status>): <body-text>`   (non-2xx HTTP)
+ *   - `OpenClaw gateway rejected request: <body.error>`  (HTTP 200, `body.ok === false`)
+ *
+ * Matchers therefore look for the granular substring **anywhere** in the string,
+ * not anchored. Our own parse failures (`Invalid llm-task response: ...` from
+ * `extractDecision`) are classified too.
+ *
+ * ## v2026.2.22 caveat
+ *
+ * On OpenClaw v2026.2.22 (current prod) the gateway collapses most `llm-task`
+ * failures into a generic `tool_error` whose message is `"tool execution failed"`,
+ * so the granular substrings frequently do **not** surface there — only on
+ * v2026.5.7+. The table is built in full anyway: on v2026.2.22 the generic
+ * `tool_error` matches {@link DecisionErrorCode.ProviderError}; on newer gateways
+ * the specific code matches.
+ */
+/** Stable identifier for each classified LLM-decision failure mode. */
+export var DecisionErrorCode;
+(function (DecisionErrorCode) {
+    /** Gateway auth token missing in env/config — thrown before any HTTP call. */
+    DecisionErrorCode["GatewayTokenMissing"] = "GATEWAY_TOKEN_MISSING";
+    /** `fetch()` rejected before a response (connection refused/reset/DNS). */
+    DecisionErrorCode["GatewayUnreachable"] = "GATEWAY_UNREACHABLE";
+    /** Gateway returned 404 — plugin not installed at this path / version mismatch. */
+    DecisionErrorCode["PluginEndpointMissing"] = "PLUGIN_ENDPOINT_MISSING";
+    /** `llm-task` invoked with empty/whitespace prompt — missing `decision_prompt`. */
+    DecisionErrorCode["PromptRequired"] = "PROMPT_REQUIRED";
+    /** `decision_model` did not resolve to a known provider/model pair. */
+    DecisionErrorCode["ProviderModelUnresolved"] = "PROVIDER_MODEL_UNRESOLVED";
+    /** Resolved model is not on the gateway's `allowedModels` allowlist. */
+    DecisionErrorCode["ModelNotAllowed"] = "MODEL_NOT_ALLOWED";
+    /** Context/payload passed to `llm-task` was not JSON-serializable — internal bug. */
+    DecisionErrorCode["InputNotSerializable"] = "INPUT_NOT_SERIALIZABLE";
+    /** Provider responded but produced no text (safety filter / refusal / empty completion). */
+    DecisionErrorCode["LlmEmptyOutput"] = "LLM_EMPTY_OUTPUT";
+    /** Model reply could not be parsed as JSON (truncation / prose around JSON). */
+    DecisionErrorCode["LlmInvalidJson"] = "LLM_INVALID_JSON";
+    /** Model reply was valid JSON but failed schema validation. */
+    DecisionErrorCode["LlmSchemaMismatch"] = "LLM_SCHEMA_MISMATCH";
+    /** Upstream provider error (rate limit / outage) or generic `tool_error`. */
+    DecisionErrorCode["ProviderError"] = "PROVIDER_ERROR";
+    /** Gateway/upstream timeout (408/504) or runtime-side abort — we already waited 90s. */
+    DecisionErrorCode["Timeout"] = "TIMEOUT";
+    /** Embedded LLM helper failed to load on the host — corrupt/partial OpenClaw install. */
+    DecisionErrorCode["EmbeddedAgentUnavailable"] = "EMBEDDED_AGENT_UNAVAILABLE";
+    /** Thinking level string does not normalize to any known level (v2026.5.7+). */
+    DecisionErrorCode["InvalidThinkingLevel"] = "INVALID_THINKING_LEVEL";
+    /** Thinking level is known but unsupported by the resolved model (v2026.5.7+). */
+    DecisionErrorCode["ThinkingLevelUnsupported"] = "THINKING_LEVEL_UNSUPPORTED";
+    /** Gateway returned 200 with a response shape this plugin can't parse — internal bug. */
+    DecisionErrorCode["PluginResponseShape"] = "PLUGIN_RESPONSE_SHAPE";
+    /** Any other 5xx with no recognizable structured body. */
+    DecisionErrorCode["OpenClawUnexpected"] = "OPENCLAW_UNEXPECTED";
+    /** No matcher matched — surfaces the raw message so operators can still diagnose. */
+    DecisionErrorCode["Unknown"] = "UNKNOWN";
+})(DecisionErrorCode || (DecisionErrorCode = {}));
+/**
+ * The single catalog of every user-facing message, keyed by {@link DecisionErrorCode}.
+ *
+ * Templates use `{token}` placeholders, filled by the matching entry's `vars`
+ * function in {@link DECISION_ERROR_TABLE} (e.g. `{name}` = action name, `{model}`,
+ * `{list}`, `{errors}`, `{level}`, `{hint}`, `{providerModel}`, `{raw}`). A `{token}`
+ * with no supplied value is left verbatim so a missing var is visible, not silent.
+ *
+ * **This is the only place to edit copy.** Nothing else hardcodes a message.
+ */
+export const DECISION_ERROR_MESSAGES = {
+    [DecisionErrorCode.GatewayTokenMissing]: "Senpi: OpenClaw gateway token not configured. Set OPENCLAW_GATEWAY_TOKEN.",
+    [DecisionErrorCode.GatewayUnreachable]: "Senpi: OpenClaw Gateway is unreachable.",
+    [DecisionErrorCode.PluginEndpointMissing]: "Senpi: OpenClaw is missing the plugin endpoint. Please reinstall the plugin.",
+    [DecisionErrorCode.PromptRequired]: "Your agent can't trade until its template is fixed. Action `{name}` in your runtime YAML is " +
+        "missing a `decision_prompt`. To recover: delete this runtime, ask your OpenClaw agent to add a " +
+        "`decision_prompt` to that action, and install it again. If you didn't write this skill, contact " +
+        "Senpi support.",
+    [DecisionErrorCode.ProviderModelUnresolved]: "Your agent can't trade because the AI model `{model}` isn't recognized by your OpenClaw host. " +
+        "To recover: delete this runtime, set a valid `decision_model` in your runtime YAML, and install it " +
+        "again. If you didn't write this skill, contact Senpi support.",
+    [DecisionErrorCode.ModelNotAllowed]: "Your agent can't trade because `{model}` isn't on your OpenClaw host's allowed-models list. " +
+        "Allowed: `{list}`. To recover: pick a model from the allowed list (delete the runtime, edit " +
+        "`decision_model` in the runtime YAML, install again) or add it to your host's allowedModels config.",
+    [DecisionErrorCode.InputNotSerializable]: "Your agent hit an internal bug while building the AI request (data wasn't serializable). Please " +
+        "report this to Senpi support — it isn't something you can fix from your side.",
+    [DecisionErrorCode.LlmEmptyOutput]: "Your agent dropped one signal because the AI model returned no answer. This is usually a safety " +
+        "filter or a transient model quirk. If it keeps happening, try a different `decision_model` in your " +
+        "runtime YAML (delete the runtime, edit, reinstall) or rephrase your `decision_prompt` to be less " +
+        "ambiguous.",
+    [DecisionErrorCode.LlmInvalidJson]: "Your agent dropped one signal because the AI model's reply wasn't valid JSON — usually a truncation " +
+        "or a prompt that didn't force JSON output. To recover: tighten your `decision_prompt` in the runtime " +
+        "YAML to require strict JSON, then delete and reinstall the runtime. If you didn't write this skill, " +
+        "contact Senpi support.",
+    [DecisionErrorCode.LlmSchemaMismatch]: "Your agent dropped one signal because the AI model's reply was valid JSON but didn't match the " +
+        "expected shape: `{errors}`. To recover: tweak your `decision_prompt` so the model returns the " +
+        "required fields, or have your OpenClaw agent loosen the schema (delete the runtime, edit the YAML, " +
+        "reinstall). If you didn't write this skill, contact Senpi support.",
+    [DecisionErrorCode.ProviderError]: "Your agent dropped one signal because the AI provider rejected the call (e.g. rate limit or outage). " +
+        "Usually transient — the next signal often goes through. If it keeps happening, try switching " +
+        "providers or using a different `decision_model` in your runtime YAML.",
+    [DecisionErrorCode.Timeout]: "Your agent dropped one signal because the AI model didn't reply in 90 seconds. This is usually " +
+        "transient — the next signal often goes through. If it keeps happening, switch to a faster " +
+        "`decision_model` in your runtime YAML (delete the runtime, edit, reinstall).",
+    [DecisionErrorCode.EmbeddedAgentUnavailable]: "Your agent dropped one signal because OpenClaw's internal LLM helper failed to load on your host. " +
+        "This usually means the OpenClaw install is corrupted or partially upgraded. To recover: reinstall " +
+        "OpenClaw on your host (or upgrade to the latest version — this error no longer exists in v2026.5.7+). " +
+        "If it keeps happening after reinstall, contact Senpi support.",
+    [DecisionErrorCode.InvalidThinkingLevel]: "Your agent's runtime YAML uses an unknown thinking level (`{level}`). Valid options: `{hint}`. " +
+        "To recover: delete this runtime, set `thinking` to a valid value in the runtime YAML, and install it " +
+        "again. If you didn't write this skill, contact Senpi support.",
+    [DecisionErrorCode.ThinkingLevelUnsupported]: "Your agent's model (`{providerModel}`) doesn't support the thinking level `{level}`. Supported for " +
+        "this model: `{hint}`. To recover: delete this runtime, change either the model or the thinking level " +
+        "in the runtime YAML, and install it again.",
+    [DecisionErrorCode.PluginResponseShape]: "Your agent hit an internal bug parsing the AI model's response. Please report this to Senpi support " +
+        "— it isn't something you can fix from your side.",
+    [DecisionErrorCode.OpenClawUnexpected]: "Senpi: Signal Dropped - OpenClaw hit an unexpected error.",
+    [DecisionErrorCode.Unknown]: "Senpi: Trading decision failed — {raw}",
+};
+/** Trim a captured token; falls back to `fallback` when empty/absent. */
+function clean(value, fallback) {
+    const t = value?.trim();
+    return t && t.length > 0 ? t : fallback;
+}
+/** Fill `{token}` placeholders from `vars`; unknown tokens are left verbatim. */
+function renderTemplate(template, vars) {
+    return template.replace(/\{(\w+)\}/g, (whole, key) => Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : whole);
+}
+/**
+ * Ordered classification table — matchers + retry flag + template-variable logic.
+ * First match wins, so keep specific matchers above generic ones (e.g.
+ * `LlmEmptyOutput` before the catch-all `ProviderError`, since both can appear
+ * inside a `"rejected request: ..."` wrapper). Copy lives in
+ * {@link DECISION_ERROR_MESSAGES}, not here.
+ */
+export const DECISION_ERROR_TABLE = [
+    // ── Pre-HTTP / infra (not retryable) ──────────────────────────────────────
+    {
+        code: DecisionErrorCode.GatewayTokenMissing,
+        match: (s) => /gateway token not configured|OPENCLAW_GATEWAY_TOKEN/.test(s),
+        retryable: false,
+    },
+    {
+        code: DecisionErrorCode.GatewayUnreachable,
+        match: (s) => /^fetch failed$|fetch failed:|ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/.test(s),
+        retryable: false,
+    },
+    {
+        code: DecisionErrorCode.PluginEndpointMissing,
+        match: (s) => /OpenClaw gateway error \(404\)/.test(s),
+        retryable: false,
+    },
+    // ── Author/config errors surfaced by llm-task (not retryable) ─────────────
+    {
+        code: DecisionErrorCode.PromptRequired,
+        match: (s) => /prompt required/i.test(s),
+        retryable: false,
+        vars: (_caps, ctx) => ({ name: clean(ctx.actionName, "<name>") }),
+    },
+    {
+        code: DecisionErrorCode.ProviderModelUnresolved,
+        match: (s) => s.match(/provider\/model could not be resolved \(provider=(.*?), model=(.*?)\)/),
+        retryable: false,
+        vars: (caps, ctx) => ({ model: clean(caps?.[2], clean(ctx.model, "your configured model")) }),
+    },
+    {
+        code: DecisionErrorCode.ModelNotAllowed,
+        match: (s) => s.match(/Model not allowed by llm-task plugin config:\s*([^.]+)\.\s*Allowed models:\s*([^"}]+)/),
+        retryable: false,
+        vars: (caps, ctx) => ({
+            model: clean(caps?.[1], clean(ctx.model, "that model")),
+            list: clean(caps?.[2], "(see your host's allowedModels config)"),
+        }),
+    },
+    {
+        code: DecisionErrorCode.InputNotSerializable,
+        match: (s) => /input must be JSON-serializable/i.test(s),
+        retryable: false,
+    },
+    // ── Model output problems ─────────────────────────────────────────────────
+    {
+        // Retryable: usually a transient safety-filter block or empty completion.
+        code: DecisionErrorCode.LlmEmptyOutput,
+        match: (s) => /LLM returned empty output/i.test(s),
+        retryable: true,
+    },
+    {
+        // Not retryable: a fixed prompt that fails to force JSON will fail identically.
+        code: DecisionErrorCode.LlmInvalidJson,
+        match: (s) => /LLM returned invalid JSON/i.test(s),
+        retryable: false,
+    },
+    {
+        // Not retryable: deterministic given a fixed prompt + schema.
+        code: DecisionErrorCode.LlmSchemaMismatch,
+        match: (s) => s.match(/LLM JSON did not match schema:\s*([^"}]+)/),
+        retryable: false,
+        vars: (caps) => ({ errors: clean(caps?.[1], "(schema validation failed)") }),
+    },
+    // ── Thinking-level misconfig (v2026.5.7+, not retryable) ──────────────────
+    {
+        code: DecisionErrorCode.InvalidThinkingLevel,
+        match: (s) => s.match(/Invalid thinking level "(.*?)"\.\s*Use one of:\s*([^"}]+?)\./),
+        retryable: false,
+        vars: (caps) => ({
+            level: clean(caps?.[1], "that value"),
+            hint: clean(caps?.[2], "the supported levels"),
+        }),
+    },
+    {
+        code: DecisionErrorCode.ThinkingLevelUnsupported,
+        match: (s) => s.match(/Thinking level "(.*?)" is not supported for (.+?)\.\s*Use one of:\s*([^"}]+?)\./),
+        retryable: false,
+        vars: (caps, ctx) => ({
+            level: clean(caps?.[1], "that level"),
+            providerModel: clean(caps?.[2], clean(ctx.model, "this model")),
+            hint: clean(caps?.[3], "the supported levels"),
+        }),
+    },
+    // ── Host/load failure (not retryable) ─────────────────────────────────────
+    {
+        code: DecisionErrorCode.EmbeddedAgentUnavailable,
+        match: (s) => /runEmbeddedPiAgent not available/.test(s),
+        retryable: false,
+    },
+    {
+        code: DecisionErrorCode.PluginResponseShape,
+        match: (s) => /Invalid llm-task response/.test(s),
+        retryable: false,
+    },
+    // ── Transient transport (timeout NOT retried; provider errors ARE) ────────
+    {
+        // Not retryable: we already waited 90s, and signal processing is strictly
+        // serial — retrying would stall the whole runtime's queue (see runtime.ts).
+        code: DecisionErrorCode.Timeout,
+        match: (s) => /OpenClaw gateway error \(408\)|OpenClaw gateway error \(504\)|AbortError|operation was aborted/.test(s),
+        retryable: false,
+    },
+    {
+        // Retryable: rate limit / transient outage / generic tool_error (the shape
+        // v2026.2.22 collapses empty-output and provider blips into).
+        code: DecisionErrorCode.ProviderError,
+        match: (s) => (/OpenClaw gateway error \(5\d\d\)/.test(s) && /"type":\s*"tool_error"|tool execution failed/.test(s)) ||
+            /OpenClaw gateway error \(429\)/.test(s) ||
+            /OpenClaw gateway rejected request/.test(s) ||
+            /tool execution failed/.test(s),
+        retryable: true,
+    },
+    {
+        // Any other 5xx with no recognizable body. Not retryable under the locked
+        // policy (only tool_error-carrying 5xx / 429 retry).
+        code: DecisionErrorCode.OpenClawUnexpected,
+        match: (s) => /OpenClaw gateway error \(5\d\d\)/.test(s),
+        retryable: false,
+    },
+];
+/**
+ * Classify a raw LLM-decision error string into a {@link ClassifiedDecisionError}.
+ *
+ * Walks {@link DECISION_ERROR_TABLE} in order; the first matching entry wins. If
+ * nothing matches, returns {@link DecisionErrorCode.Unknown} (not retryable). The
+ * message is always rendered from {@link DECISION_ERROR_MESSAGES}.
+ *
+ * @param rawMessage - The error string thrown by the decision client (may embed an
+ *   OpenClaw gateway message). Non-string / empty inputs are coerced safely.
+ * @param ctx - Optional plugin-side context for placeholders the gateway can't supply.
+ */
+export function classifyDecisionError(rawMessage, ctx = {}) {
+    const raw = typeof rawMessage === "string" ? rawMessage : String(rawMessage ?? "");
+    for (const entry of DECISION_ERROR_TABLE) {
+        const result = entry.match(raw);
+        if (!result)
+            continue;
+        const caps = Array.isArray(result) ? result : null;
+        const vars = entry.vars ? entry.vars(caps, ctx, raw) : {};
+        return {
+            code: entry.code,
+            retryable: entry.retryable,
+            userMessage: renderTemplate(DECISION_ERROR_MESSAGES[entry.code], vars),
+        };
+    }
+    return {
+        code: DecisionErrorCode.Unknown,
+        retryable: false,
+        userMessage: renderTemplate(DECISION_ERROR_MESSAGES[DecisionErrorCode.Unknown], { raw }),
+    };
+}
+/**
+ * Convenience predicate for retry wiring: `true` when a retry of the failed
+ * `llm-task` call can plausibly succeed.
+ *
+ * @param error - The thrown error (or any value); only its message is inspected.
+ */
+export function isRetryableDecisionError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return classifyDecisionError(message).retryable;
+}
+//# sourceMappingURL=decision-errors.js.map

package/dist/runtime/decision-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-errors.js","sourceRoot":"","sources":["../../src/runtime/decision-errors.ts"],"names":[],"mappings":"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"}

package/dist/runtime/notifications.d.ts

@@ -1,5 +1,6 @@
 import type { McpTransport } from "../senpi/types.js";
 import type { NotificationService } from "../types/notification.js";
+import { type DecisionErrorContext } from "./decision-errors.js";
 export interface NotificationServiceOptions {
     telegram_chat_id?: string;
     mcpTransport?: McpTransport;
@@ -7,7 +8,20 @@ export interface NotificationServiceOptions {
     gateway_token?: string;
     [key: string]: unknown;
 }
-export declare function formatDecisionErrorNotification(rawMessage: string): string;
+/**
+ * Map a raw LLM-decision error string to the user-facing Telegram message.
+ *
+ * Thin wrapper over {@link classifyDecisionError} — all message wording and the
+ * failure-mode lookup live in `decision-errors.ts` (the single source of truth
+ * shared with the retry logic in `openclaw-llm-decision.ts`). The runtime catches
+ * errors from the LLM-decision call and passes `err.message` here.
+ *
+ * @param rawMessage - Error message thrown by the decision client (may embed an
+ *   OpenClaw gateway message).
+ * @param ctx - Optional plugin-side context (action name, configured model) for
+ *   placeholders the gateway error string cannot supply.
+ */
+export declare function formatDecisionErrorNotification(rawMessage: string, ctx?: DecisionErrorContext): string;
 /**
  * IMPORTANT: Do NOT use logger.error(...) anywhere inside this service.
  * NotificationService is itself the Telegram delivery path for error notifications.

package/dist/runtime/notifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/runtime/notifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAKpE,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAmBD,wBAAgB,+BAA+B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAiD1E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,mBAAmB,CAyEnG"}
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/runtime/notifications.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,EAAyB,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAIxF,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,oBAAoB,GACzB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,mBAAmB,CAyEnG"}

package/dist/runtime/notifications.js

@@ -1,62 +1,21 @@
 import { createLogger } from "../utils/logger.js";
+import { classifyDecisionError } from "./decision-errors.js";
 const logger = createLogger("[senpi-core][notifications]");
-// Decision-error → user-facing chat message.
-//
-// The runtime catches errors from the LLM-decision call (openclaw-llm-decision.ts:
-// throws on token-missing, on non-2xx HTTP, and on body.ok=false) and passes
-// err.message here. Network-level failures (fetch() rejecting) also reach this
-// with the underlying error string.
-//
-// Discriminators: HTTP status prefix + presence of a structured tool_error body
-// + node fetch error markers. The mapping below is intentionally specific per
-// failure mode so the chat reader can tell apart:
-//   - infrastructure unreachable vs misconfigured,
-//   - signal dropped because the AI model timed out vs the AI model errored vs
-//     OpenClaw itself returned an unexpected error.
-// Auth (401/403) is intentionally NOT handled separately — the runtime plugin
-// and the gateway it calls share the same process env and the same token, so
-// 401/403 is unreachable in practice; if it ever fires, the generic fallback
-// at the bottom surfaces the raw message.
-export function formatDecisionErrorNotification(rawMessage) {
-    const s = rawMessage;
-    // Token missing at config-time — fires before any HTTP call, so check first.
-    if (/gateway token not configured|OPENCLAW_GATEWAY_TOKEN/.test(s)) {
-        return "Senpi: OpenClaw gateway token not configured. Set OPENCLAW_GATEWAY_TOKEN.";
-    }
-    // (1) OpenClaw Gateway not reachable — fetch() rejected before getting a
-    // response. Node's undici fetch surfaces these as "fetch failed" with the
-    // underlying SystemError code in .cause; the action runner stringifies it
-    // so the code marker usually lands in the message.
-    if (/^fetch failed$|fetch failed:|ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/.test(s)) {
-        return "Senpi: OpenClaw Gateway is unreachable.";
-    }
-    // (2) Endpoint missing — plugin not installed at this path, or version mismatch.
-    if (/OpenClaw gateway error \(404\)/.test(s)) {
-        return "Senpi: OpenClaw is missing the plugin endpoint. Please reinstall the plugin.";
-    }
-    // (3) AI model timed out — OpenClaw's llm-task tool returns 408 when it hits
-    // its own per-call cap; the gateway returns 504 when the upstream call exceeded
-    // the gateway's frame timeout. AbortError covers cancellation paths that may
-    // be added at the runtime side in the future.
-    if (/OpenClaw gateway error \(408\)|OpenClaw gateway error \(504\)|AbortError|operation was aborted/.test(s)) {
-        return "Senpi: Signal Dropped - AI model didn't respond in 90 seconds.";
-    }
-    // (4) AI model failed — HTTP 5xx whose body carries a structured tool_error
-    // (today's case: Gemini overload → llm-task wraps as `{"ok":false,
-    // "error":{"type":"tool_error","message":"tool execution failed"}}` →
-    // gateway returns HTTP 500), OR HTTP 200 with body.ok=false from the same
-    // tool layer ("OpenClaw gateway rejected request: ...").
-    if ((/OpenClaw gateway error \(5\d\d\)/.test(s) && /"type":\s*"tool_error"/.test(s)) ||
-        /OpenClaw gateway rejected request/.test(s)) {
-        return "Senpi: Signal Dropped - AI model failed to respond.";
-    }
-    // (5) Any other 5xx — gateway-frame error or unparseable body.
-    if (/OpenClaw gateway error \(5\d\d\)/.test(s)) {
-        return "Senpi: Signal Dropped - OpenClaw hit an unexpected error.";
-    }
-    // Last-resort generic prefix — surfaces the underlying message so operators
-    // can still diagnose unknown failure modes from the chat.
-    return `Senpi: Trading decision failed — ${s}`;
+/**
+ * Map a raw LLM-decision error string to the user-facing Telegram message.
+ *
+ * Thin wrapper over {@link classifyDecisionError} — all message wording and the
+ * failure-mode lookup live in `decision-errors.ts` (the single source of truth
+ * shared with the retry logic in `openclaw-llm-decision.ts`). The runtime catches
+ * errors from the LLM-decision call and passes `err.message` here.
+ *
+ * @param rawMessage - Error message thrown by the decision client (may embed an
+ *   OpenClaw gateway message).
+ * @param ctx - Optional plugin-side context (action name, configured model) for
+ *   placeholders the gateway error string cannot supply.
+ */
+export function formatDecisionErrorNotification(rawMessage, ctx) {
+    return classifyDecisionError(rawMessage, ctx).userMessage;
 }
 /**
  * IMPORTANT: Do NOT use logger.error(...) anywhere inside this service.