solana-traderclaw 1.0.146 → 1.0.147

package/dist/index.js

@@ -48,6 +48,7 @@ import { Type } from "@sinclair/typebox";
 import kayba, { SpanType } from "@kayba_ai/tracing";
 import * as fs from "fs";
 import * as path from "path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "os";
 
 // lib/x-client.mjs
@@ -802,6 +803,16 @@ function getOrCreateAlphaLifetimeState() {
   __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_ALPHA_LIFETIME_SINGLETON_KEY] = fresh;
   return fresh;
 }
+var __solanaTraderStatusQueriesMd = (() => {
+  try {
+    const distPath = fileURLToPath(import.meta.url);
+    const packageRoot = path.dirname(path.dirname(distPath));
+    const mdPath = path.join(packageRoot, "lib", "status-queries.md");
+    return fs.readFileSync(mdPath, "utf-8");
+  } catch {
+    return void 0;
+  }
+})();
 function __solanaTraderDisposePreviousLifecycle(logger) {
   const prev = __solanaTraderGlobalSingletonHolder[SOLANA_TRADER_LIFECYCLE_SINGLETON_KEY];
   if (!prev) return;
@@ -4298,6 +4309,14 @@ ${String(params.summary)}
           content: "# Live alpha status queries \u2014 always call the tool\n\nWhen the user asks anything about CURRENT alpha activity, call the matching tool **on this turn**. Do NOT answer from memory, heartbeat history, journal logs, or earlier turn context \u2014 alpha signals are not journalled per-message, so 'I don't see any / 0' is wrong by default.\n\n## Routing\n\n| User question shape | Tool(s) to call | Key fields in response |\n|---|---|---|\n| how many alpha signals / are we getting alpha / activity since gateway start | `solana_alpha_signals` (unseen:false) | stats.messageCount, stats.lifetimeUptimeSeconds, stats.lastEventTs, subscribed, bufferSize |\n| is alpha connected / healthy / stream status | `solana_alpha_signals` (unseen:false) | subscribed, stats.reconnectAttempt, stats.unhealthyStreak, stats.circuitBackoff, stats.lastEventTs |\n| how many alpha signals in last hour / today / this week / since <day> | `solana_alpha_signals` (live state) **AND** `solana_alpha_history` (days=\u2026 or compute from window) | live: stats.messageCount + bufferSize; historical: pings[] in window |\n| any alpha on token <X> (recent / historical) | `solana_alpha_signals` for in-buffer signals, then `solana_alpha_history` (tokenAddress=X, days=N) for older | both responses merged by ts |\n| what alpha sources / channels are active | `solana_alpha_sources` | sources[] (name, type, count, avgScore) |\n| latest signals / new signals | `solana_alpha_signals` (unseen:false) | signals[] sorted newest last |\n\n## Field meanings \u2014 IMPORTANT\n\n`solana_alpha_signals` returns `stats` with both lifetime and current-WS fields. Use LIFETIME fields for user-facing answers:\n\n- `stats.messageCount` = **lifetime** total alpha_signal messages received since the gateway process started. Survives plugin re-registers and WS reconnects. **This is the headline number.**\n- `stats.lifetimeUptimeSeconds` = seconds since the first WS open in this process.\n- `stats.lastEventTs` = wall-clock ms of the most recent signal (lifetime).\n- `stats.firstConnectedAt` = wall-clock ms of the first WS open in this process.\n\nDebug-only (do NOT report these as 'totals' \u2014 they reset on every WS reconnect / plugin re-register):\n\n- `stats.currentWsMessageCount` \u2014 messages since the current WS opened.\n- `stats.uptimeSeconds` \u2014 current WS uptime.\n- `stats.connectedAt` \u2014 current WS open ts.\n\n## When to also call `solana_alpha_history`\n\nCall `solana_alpha_history` in addition to `solana_alpha_signals` whenever the user's window pre-dates the current gateway-process lifetime (e.g. `stats.lifetimeUptimeSeconds` is shorter than the asked window, or `stats.messageCount` is 0 because the gateway just restarted). Tier=enterprise returns up to 200 pings, up to ~1 year back.\n\n## Reply template (live-only)\n\n```\nLive alpha state:\n- subscribed: <bool>\n- lifetime: <messageCount> messages over <lifetimeUptimeSeconds>s (\u2248 <rate>/min) since gateway start\n- last signal: <Xs/Xm ago> (lastEventTs)\n- buffer (deduped): <bufferSize>\n- reconnects: <reconnectAttempt>, unhealthy streak: <unhealthyStreak>\n```\n\n## Reply template (with historical window, e.g. 'last hour')\n\n```\nAlpha activity (<window>):\n- live (gateway lifetime): <messageCount> messages over <lifetimeUptimeSeconds>s\n- historical (`solana_alpha_history` days=<N>): <pings.length> pings\n- combined unique within <window>: <merged count>\n- subscribed: <bool>, last signal: <ago>\n```\n\nThis routing overrides any heartbeat-cycle 'minimal calls' cap: ad-hoc user status questions are NOT subject to per-cycle envelopes.\n",
           source: "solana-trader:live-queries"
         });
+        if (__solanaTraderStatusQueriesMd) {
+          context.bootstrapFiles.push({
+            name: "STATUS_QUERIES.md",
+            path: "STATUS_QUERIES.md",
+            content: __solanaTraderStatusQueriesMd,
+            source: "solana-trader:status-queries"
+          });
+        }
         api.logger.info(`[solana-trader] Bootstrap: injected ${context.bootstrapFiles.length} files for agent ${bootAgentId}`);
       },
       {

package/lib/status-queries.md

@@ -0,0 +1,103 @@
+# Live status queries — always call the tool, never answer from memory
+
+When the user asks any question about **current alpha stream state**, you MUST call the matching plugin tool **on this turn**, then summarize what the tool returned. Do NOT answer from memory, heartbeat history, journal logs, log snippets, or earlier conversation context: alpha counts grow second-by-second and stale answers (especially "none" / "zero") are wrong by default.
+
+## Why this rule exists
+
+The plugin does NOT log every received alpha signal to the journal (that would be noisy at sustained throughput). Signal counts and the buffer of recent signals live **only inside the running plugin process** and are exposed via these tools. If you don't call the tool, you have no data — you only have the absence of log lines, which is not the same thing.
+
+The heartbeat history (`memory/<date>.md`, `MEMORY.md`) only captures signals the agent **personally evaluated** during a heartbeat cycle. It is NOT a record of what the WebSocket received. Using heartbeat history to answer "how many signals" gives a count that is typically much smaller than the real number (because most signals never reach a cycle where the agent processes them).
+
+## Alpha question → tool routing
+
+When the user's question matches a row in column 1, call the tool(s) in column 2 (always on this turn, before replying), read the response, and answer from that data.
+
+| User question (or similar) | Call this tool | What to report back |
+|---|---|---|
+| "how many alpha signals have we gotten?" / "are we getting alpha?" / "anything from alpha lately?" | `solana_alpha_signals` (with `unseen: false`) | `stats.messageCount` (LIFETIME — survives re-registers/reconnects), `stats.lifetimeUptimeSeconds`, `stats.lastEventTs`, `subscribed`, `bufferSize` |
+| "what's the alpha stream doing right now?" / "is alpha connected?" / "alpha health?" | `solana_alpha_signals` (with `unseen: false`) | `subscribed`, `stats.reconnectAttempt`, `stats.unhealthyStreak`, `stats.circuitBackoff`, `stats.lastEventTs` (interpret as "Xs ago") |
+| "how many alpha signals in the last hour / today / this week / since Monday?" | `solana_alpha_signals` (live) **AND** `solana_alpha_history` (`days=` covering the window) | Live: `stats.messageCount` since gateway start + signals in `signals[]` within the window. Historical: pings in window from REST. Report both. |
+| "any alpha on `<token>` recently / in the last 24h?" | `solana_alpha_signals` (filter `signals[]` by `tokenAddress`/`tokenSymbol`) **AND** `solana_alpha_history` (`tokenAddress=<addr>&days=N`) | Merge live + historical signals for that token by timestamp. |
+| "what alpha sources are active?" / "which channels are sending signals?" | `solana_alpha_sources` | `sources` array — name, type, count, avgScore per channel |
+| "show me the latest alpha signals" / "new signals?" | `solana_alpha_signals` (with `unseen: false` for full buffer, `unseen: true` only if you intend to consume) | Up to N signals: token, source, kind, signalStage, marketCap, systemScore, ts |
+
+## `stats` fields — what to use vs. what to ignore
+
+`solana_alpha_signals` returns a `stats` object with both **lifetime** and **per-current-WS** fields. **Always quote the lifetime fields to the user.**
+
+USE these for user-facing answers (stable across plugin re-registers and WS reconnects):
+
+- `stats.messageCount` — **lifetime** total alpha_signal messages received since the gateway process started.
+- `stats.lifetimeUptimeSeconds` — seconds since the first WebSocket open in this gateway process.
+- `stats.lastEventTs` — wall-clock ms of the most recent signal (lifetime).
+- `stats.firstConnectedAt` — wall-clock ms of the first WS open in this process.
+
+DO NOT use as "totals" (they reset on every WS reconnect / plugin re-register, which happens every agent turn — so the numbers are misleading as standalone answers):
+
+- `stats.currentWsMessageCount` — messages since the CURRENT WS opened. Useful only for debugging "why is the WS cycling?".
+- `stats.uptimeSeconds` — current WS uptime.
+- `stats.connectedAt` — current WS open ts.
+
+## When to also call `solana_alpha_history`
+
+The live tool gives you "messages since this gateway process started" and a buffer of ~200 deduped signals. For windows that exceed those:
+
+- The asked window predates `stats.firstConnectedAt` (e.g. user asks "last 24h" but gateway started 2h ago).
+- The user asks about a specific date or named window ("yesterday", "since Monday", "last week").
+- The buffer is empty (e.g. just after a gateway restart) but the user is asking about a real time range.
+
+…ALSO call `solana_alpha_history` (`days=N` covering the window) and combine the two responses. Tier=enterprise → up to 200 results back ~1 year.
+
+## How to answer (template — live-only)
+
+After the tool returns, structure your reply like this so the user can verify you queried live data:
+
+```
+Live alpha state (as of <now>):
+- subscribed: <subscribed>
+- lifetime: <stats.messageCount> messages over <stats.lifetimeUptimeSeconds>s (≈ <rate>/min) since gateway start
+- last signal: <stats.lastEventTs as "Xs/Xm ago">
+- buffer (deduped, ≤200): <bufferSize>
+- reconnects: <stats.reconnectAttempt>, unhealthy streak: <stats.unhealthyStreak>
+
+Top sources (from `solana_alpha_sources`):
+- <sourceName> (<sourceType>): <count> signals, avg score <avgScore>
+
+Sample of latest signals (newest first):
+- <tokenSymbol> (<tokenName>) — <kind>/<signalStage>, MC $<marketCap>, score <systemScore>, from <sourceName>, <ts ago>
+```
+
+## How to answer (template — when window > gateway lifetime)
+
+```
+Alpha activity (<window>):
+- live (gateway lifetime, <lifetimeUptimeSeconds>s): <messageCount> messages, currently <bufferSize> in buffer
+- historical (`solana_alpha_history` days=<N>): <pings.length> pings in window
+- combined unique: <merged count>
+- subscribed: <bool>, last signal: <ago>
+
+Top historical sources / tokens: …
+```
+
+## Common mistakes to avoid
+
+- **Don't answer "zero" or "none" without calling the tool.** "I don't see any in the logs / heartbeat history" is wrong — signals are NOT logged per-message and heartbeat history only captures what the agent itself touched.
+- **Don't reuse a count from earlier in the conversation.** The buffer is continuously updated; quote only freshly-fetched numbers.
+- **Don't quote `currentWsMessageCount` or `uptimeSeconds` as "totals".** Those reset every time you (or anyone) interacts with the agent, because each interaction re-registers the plugin. Always use `stats.messageCount` and `stats.lifetimeUptimeSeconds` for user-facing answers.
+- **Don't mix heartbeat history with live tool data without flagging it.** If the user asks "how many in the last hour" and you can only see live state, say so and call `solana_alpha_history` to fill the window.
+- **Don't claim "the stream is offline" from log gaps alone.** Check `subscribed` and `stats.lastEventTs` — a stream can be healthy with low-traffic minutes.
+- **Don't paste raw JSON to the user.** Summarize per the templates above; offer raw JSON only if asked.
+
+## When the user does NOT need a tool call
+
+These are NOT live-state queries; answer from your knowledge:
+
+- "how does the alpha stream work?" (explain the design from `skills/solana-trader/refs/alpha-signals.md` if available)
+- "what's a `ca_drop`?" (definition)
+- "which alpha sources are premium?" (static info from refs)
+
+## Related
+
+- `HEARTBEAT.md` — per-heartbeat cycle envelope (separate from ad-hoc Q&A).
+- `skills/solana-trader/refs/alpha-signals.md` — full alpha pipeline reference.
+- Tool catalog: `solana_alpha_subscribe`, `solana_alpha_unsubscribe`, `solana_alpha_signals`, `solana_alpha_sources`, `solana_alpha_history`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-traderclaw",
-  "version": "1.0.146",
+  "version": "1.0.147",
   "description": "TraderClaw V1-Upgraded — Solana trading for OpenClaw with intelligence lab, tool envelopes, prompt scrubbing, read-only X social intel, and split skill docs",
   "type": "module",
   "main": "./dist/index.js",

package/skills/solana-trader/workspace/AGENTS.md

@@ -127,3 +127,21 @@ These are permanent directives. They apply every session, every cycle, without e
 4. **Always check kill switch before new entries.** Call `solana_killswitch_status()` before any new trade execution. If active, halt immediately — no exceptions, no overrides.
 
 5. **Always report every cycle.** Never run a silent heartbeat. Every cycle produces a report: what you scanned, what you found, what you did, what you skipped and why. Crypto is 24/7. Every cycle reports.
+
+## Live status questions → ALWAYS call the tool
+
+When the user asks about the **current** state of the alpha stream (counts, sources, recent signals, subscription health, or any time window), you MUST call the matching plugin tool **on the same turn** before replying. Do not answer "zero / none / I don't see anything" from memory, heartbeat history, journal logs, or log impressions — signals are not logged per-message; they live only inside the running plugin (live state) and the orchestrator REST (historical) and are surfaced via tools.
+
+See `STATUS_QUERIES.md` (auto-injected by the plugin at every register) for the full question → tool routing table, field semantics (lifetime vs. current-WS), and the standard answer template. The short version:
+
+| Question shape | Tool(s) to call |
+|---|---|
+| "how many alpha signals / are we getting alpha?" | `solana_alpha_signals` (`unseen: false`) — quote `stats.messageCount` (LIFETIME, survives re-registers) and `stats.lifetimeUptimeSeconds` |
+| "is alpha connected / healthy?" | `solana_alpha_signals` (`unseen: false`) — read `subscribed`, `stats.lastEventTs`, `stats.reconnectAttempt`, `stats.unhealthyStreak`, `stats.circuitBackoff` |
+| "how many in last hour / today / since `<day>`?" / "any alpha on `<token>` in 24h?" | `solana_alpha_signals` (live) **AND** `solana_alpha_history` (`days=N` covering the window, `tokenAddress=` when filtering) |
+| "which alpha sources / channels?" | `solana_alpha_sources` |
+| "latest / new alpha signals?" | `solana_alpha_signals` (with or without `unseen: true` depending on intent) |
+
+Field reminder: use `stats.messageCount` and `stats.lifetimeUptimeSeconds` as the headline numbers. Do NOT quote `stats.currentWsMessageCount` or `stats.uptimeSeconds` as "totals" — they reset on every plugin re-register (every agent turn / Telegram message).
+
+This rule applies to all sessions — direct chats, Telegram, anywhere the user asks. It overrides the heartbeat-cycle envelope: ad-hoc live-state questions are NOT subject to the "minimal per-cycle calls" cap.