@senpi/runtime 1.0.95-dev.runtime-phase-2.20260506193916 → 1.0.95-dev.runtime-phase-2-api.20260507130312

package/dist/runtime-api/config.js

@@ -0,0 +1,74 @@
+/**
+ * TypeBox schema and loader for the `api` block in the openclaw plugin config.
+ *
+ * The `api` block is an optional top-level property inside `openclaw.json`
+ * `plugins[*].config`. If the operator omits it entirely — or omits individual
+ * fields — this module fills in the documented defaults so the rest of the
+ * runtime-api code can rely on a fully-typed, always-present value.
+ */
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+/** TypeBox schema for the `api` config block. Mirrors openclaw.plugin.json. */
+export const ApiConfigSchema = Type.Object({
+    /**
+     * Bind interface for the HTTP server inside the openclaw container.
+     * Default `127.0.0.1` — container loopback only (most secure).
+     * Set to `0.0.0.0` to enable Docker port mapping for Postman testing.
+     * A boot-time warning is logged when this is not `127.0.0.1`.
+     */
+    host: Type.String({ default: "127.0.0.1" }),
+    /**
+     * TCP port the HTTP server listens on.
+     * Default `8787`. Must be in [1, 65535].
+     */
+    port: Type.Integer({ minimum: 1, maximum: 65535, default: 8787 }),
+    /**
+     * Maximum number of items allowed in a single `POST /signals` request body.
+     * Conservative default of `10` — operators raise it deliberately when
+     * broadcasting to many wallets at once.
+     */
+    maxItemsPerSignalsRequest: Type.Integer({
+        minimum: 1,
+        maximum: 1000,
+        default: 10,
+    }),
+}, { additionalProperties: false });
+/** Default values applied when the operator omits the `api` block or individual fields. */
+const API_CONFIG_DEFAULTS = {
+    host: "127.0.0.1",
+    port: 8787,
+    maxItemsPerSignalsRequest: 10,
+};
+/**
+ * Load and validate the `api` config block from the full plugin config object.
+ *
+ * Merges operator-supplied values over the defaults, then validates the result
+ * against {@link ApiConfigSchema}. Throws if any field is out of range or the
+ * wrong type (e.g. a port value of 99999).
+ *
+ * @param pluginConfig - The entire plugin config object as passed by openclaw to
+ *   `register(api)`. May be `undefined`, `null`, or a plain object. The function
+ *   reads only the `api` sub-key; all other keys are ignored.
+ * @returns A fully-typed {@link ApiConfig} with all defaults applied.
+ * @throws {Error} If the merged config fails TypeBox validation (e.g. port out of range).
+ */
+export function loadApiConfig(pluginConfig) {
+    const raw = pluginConfig !== null &&
+        typeof pluginConfig === "object" &&
+        "api" in pluginConfig
+        ? pluginConfig["api"]
+        : undefined;
+    const merged = {
+        ...API_CONFIG_DEFAULTS,
+        ...(raw !== null && typeof raw === "object" ? raw : {}),
+    };
+    if (!Value.Check(ApiConfigSchema, merged)) {
+        const firstError = Value.Errors(ApiConfigSchema, merged).First();
+        const detail = firstError
+            ? `${firstError.path}: ${firstError.message}`
+            : "unknown validation error";
+        throw new Error(`Invalid runtime api config — ${detail}`);
+    }
+    return merged;
+}
+//# sourceMappingURL=config.js.map

package/dist/runtime-api/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/runtime-api/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,CACxC;IACE;;;;;OAKG;IACH,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAE3C;;;OAGG;IACH,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAEjE;;;;OAIG;IACH,yBAAyB,EAAE,IAAI,CAAC,OAAO,CAAC;QACtC,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,EAAE;KACZ,CAAC;CACH,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAChC,CAAC;AAKF,2FAA2F;AAC3F,MAAM,mBAAmB,GAAc;IACrC,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,IAAI;IACV,yBAAyB,EAAE,EAAE;CAC9B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,YAAqB;IACjD,MAAM,GAAG,GACP,YAAY,KAAK,IAAI;QACrB,OAAO,YAAY,KAAK,QAAQ;QAChC,KAAK,IAAK,YAAwC;QAChD,CAAC,CAAE,YAAwC,CAAC,KAAK,CAAC;QAClD,CAAC,CAAC,SAAS,CAAC;IAEhB,MAAM,MAAM,GAAc;QACxB,GAAG,mBAAmB;QACtB,GAAG,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAE,GAA0B,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC;IAEF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,eAAe,EAAE,MAAM,CAAC,EAAE,CAAC;QAC1C,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;QACjE,MAAM,MAAM,GAAG,UAAU;YACvB,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,KAAK,UAAU,CAAC,OAAO,EAAE;YAC7C,CAAC,CAAC,0BAA0B,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,gCAAgC,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/runtime-api/handlers/audit.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared audit handler for `GET /audit`.
+ *
+ * Delegates to `RuntimeHandle.auditQuery` and translates `AuditQueryError`
+ * codes into the HTTP-layer result shape. Called by the Fastify route (S4).
+ *
+ * The discriminator field is `success` (matching MCP and the rest of the
+ * runtime-api surface). The route layer translates a successful result
+ * into the wire shape `{ success: true, data: {...} }` and a failure into
+ * `{ success: false, error: { code, message } }` per the senpi-stack
+ * convention.
+ */
+import type { AuditQueryArgs, AuditQueryResult } from "../../runtime/audit-query.types.js";
+import type { RuntimeHandle } from "../../runtime/run.js";
+import type { Logger } from "../../utils/logger.js";
+/**
+ * Dependencies injected into {@link auditHandler}.
+ */
+export interface AuditDeps {
+    /** Live runtime handles maintained by the plugin. */
+    runtimeHandles: Map<string, RuntimeHandle>;
+    /** Logger instance — unexpected errors logged at `error` level. */
+    logger: Logger;
+}
+/**
+ * Result returned by {@link auditHandler}.
+ *
+ * Discriminated on `success`:
+ * - `true`  → audit query succeeded; `address`, `strategyId`, and `result` are present.
+ * - `false` → failure; `code` is one of `NOT_FOUND | UPSTREAM | ABORTED`.
+ *
+ * `NOT_FOUND`  — no running runtime for the given address, or `listStrategies`
+ *                returned 0 matches (wallet not owned by the API-key user).
+ * `UPSTREAM`   — MCP returned an error (network, auth, schema mismatch, runtime
+ *                not started).
+ * `ABORTED`    — caller cancelled via `AbortSignal` before MCP responded.
+ */
+export type AuditHandlerResult = {
+    success: true;
+    /** Lowercased wallet address. */
+    address: string;
+    /**
+     * Strategy UUID resolved from the wallet by `listStrategies`.
+     * May be `null` on the first successful call in the unlikely window
+     * between `auditQuery` resolving and `getStrategyId()` being read —
+     * in practice the cache is populated synchronously before the
+     * Promise resolves.
+     */
+    strategyId: string | null;
+    /** Pass-through `audit_query` response payload. */
+    result: AuditQueryResult;
+} | {
+    success: false;
+    code: "NOT_FOUND" | "UPSTREAM" | "ABORTED";
+    message: string;
+};
+/**
+ * Execute an audit query for one wallet via its runtime handle.
+ *
+ * Steps:
+ * 1. Resolve the runtime handle by `address` (case-insensitive lookup).
+ *    Returns `NOT_FOUND` on miss.
+ * 2. Call `handle.auditQuery(args, { signal })`.
+ * 3. Read `handle.getStrategyId()` after a successful call — the id is cached
+ *    on the runtime instance from step 2's `listStrategies` resolution.
+ * 4. On `AuditQueryError`: map `code` straight through to the result.
+ * 5. On any other throw: log + return `UPSTREAM`.
+ *
+ * @param address  Wallet address to audit (normalised to lowercase internally).
+ * @param args     Audit query filters forwarded to `RuntimeHandle.auditQuery`.
+ * @param deps     Injected dependencies.
+ * @param signal   Optional `AbortSignal` tied to the Fastify request lifetime.
+ *                 Threads through to the underlying MCP call so the runtime
+ *                 can cancel in-flight work when the HTTP client disconnects.
+ * @returns        A resolved `AuditHandlerResult` — never rejects.
+ */
+export declare function auditHandler(address: string, args: AuditQueryArgs, deps: AuditDeps, signal?: AbortSignal): Promise<AuditHandlerResult>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/runtime-api/handlers/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/handlers/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC3C,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,OAAO,EAAE,IAAI,CAAC;IACd,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mDAAmD;IACnD,MAAM,EAAE,gBAAgB,CAAC;CAC1B,GACD;IACE,OAAO,EAAE,KAAK,CAAC;IACf,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,SAAS,EACf,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,CAAC,CAsC7B"}

package/dist/runtime-api/handlers/audit.js

@@ -0,0 +1,65 @@
+/**
+ * Shared audit handler for `GET /audit`.
+ *
+ * Delegates to `RuntimeHandle.auditQuery` and translates `AuditQueryError`
+ * codes into the HTTP-layer result shape. Called by the Fastify route (S4).
+ *
+ * The discriminator field is `success` (matching MCP and the rest of the
+ * runtime-api surface). The route layer translates a successful result
+ * into the wire shape `{ success: true, data: {...} }` and a failure into
+ * `{ success: false, error: { code, message } }` per the senpi-stack
+ * convention.
+ */
+import { findRuntimeHandleByAddress } from "./lookup.js";
+import { AuditQueryError } from "../../runtime/audit-query.types.js";
+/**
+ * Execute an audit query for one wallet via its runtime handle.
+ *
+ * Steps:
+ * 1. Resolve the runtime handle by `address` (case-insensitive lookup).
+ *    Returns `NOT_FOUND` on miss.
+ * 2. Call `handle.auditQuery(args, { signal })`.
+ * 3. Read `handle.getStrategyId()` after a successful call — the id is cached
+ *    on the runtime instance from step 2's `listStrategies` resolution.
+ * 4. On `AuditQueryError`: map `code` straight through to the result.
+ * 5. On any other throw: log + return `UPSTREAM`.
+ *
+ * @param address  Wallet address to audit (normalised to lowercase internally).
+ * @param args     Audit query filters forwarded to `RuntimeHandle.auditQuery`.
+ * @param deps     Injected dependencies.
+ * @param signal   Optional `AbortSignal` tied to the Fastify request lifetime.
+ *                 Threads through to the underlying MCP call so the runtime
+ *                 can cancel in-flight work when the HTTP client disconnects.
+ * @returns        A resolved `AuditHandlerResult` — never rejects.
+ */
+export async function auditHandler(address, args, deps, signal) {
+    const normalizedAddress = address.toLowerCase();
+    const lookup = findRuntimeHandleByAddress(deps.runtimeHandles, normalizedAddress);
+    if (!lookup.found) {
+        return { success: false, code: "NOT_FOUND", message: lookup.message };
+    }
+    const { handle } = lookup;
+    try {
+        const result = await handle.auditQuery(args, { signal });
+        // getStrategyId() is synchronous — the cache is populated by auditQuery
+        // before the awaited Promise resolves, so this is always set on success.
+        const strategyId = handle.getStrategyId();
+        return {
+            success: true,
+            address: normalizedAddress,
+            strategyId,
+            result,
+        };
+    }
+    catch (err) {
+        if (err instanceof AuditQueryError) {
+            return { success: false, code: err.code, message: err.message };
+        }
+        const message = err instanceof Error
+            ? err.message
+            : `Unexpected audit error: ${String(err)}`;
+        deps.logger.error("[senpi-core][runtime-api][audit] Unexpected error during audit query", { address: normalizedAddress, err });
+        return { success: false, code: "UPSTREAM", message };
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/runtime-api/handlers/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/runtime-api/handlers/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAqDrE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,IAAoB,EACpB,IAAe,EACf,MAAoB;IAEpB,MAAM,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAEhD,MAAM,MAAM,GAAG,0BAA0B,CAAC,IAAI,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;IAClF,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACxE,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAEzD,wEAAwE;QACxE,yEAAyE;QACzE,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;QAE1C,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,iBAAiB;YAC1B,UAAU;YACV,MAAM;SACP,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;YACnC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAClE,CAAC;QAED,MAAM,OAAO,GACX,GAAG,YAAY,KAAK;YAClB,CAAC,CAAC,GAAG,CAAC,OAAO;YACb,CAAC,CAAC,2BAA2B,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,sEAAsE,EACtE,EAAE,OAAO,EAAE,iBAAiB,EAAE,GAAG,EAAE,CACpC,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACvD,CAAC;AACH,CAAC"}

package/dist/runtime-api/handlers/group-by-scanner.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure helper that groups a flat `SignalItem[]` by `(address, scanner)` so
+ * the route handler can fan-out groups in parallel while keeping items within
+ * a group sequential — dodging the per-(address, scanner) ingest lock held by
+ * `ScannerEngine` during async ingest
+ * (`src/scanners/engine/engine.ts:282-287`).
+ */
+import type { SignalItem } from "./types.js";
+/**
+ * A `SignalItem` paired with its original zero-based index in the input array.
+ * The index is used to re-flatten grouped results back into the caller's
+ * requested order after `Promise.all` group settlement.
+ */
+export interface IndexedSignalItem {
+    /** Zero-based position in the original input array. */
+    index: number;
+    /** The original signal item. */
+    item: SignalItem;
+}
+/**
+ * A sequence of items that share the same `(lowercased address, scanner)` key
+ * and must be processed sequentially to avoid the per-(address, scanner) lock.
+ */
+export type SignalGroup = IndexedSignalItem[];
+/**
+ * Group signal items by `(lowercased address, scanner)`.
+ *
+ * Items within a group must be processed sequentially — the runtime's scanner
+ * engine holds a per-(address, scanner) mutex during the full async ingest
+ * chain and throws `UNAVAILABLE` on concurrent calls for the same key.
+ *
+ * Groups with different keys (different address or different scanner) can be
+ * processed in parallel — they do not share the lock.
+ *
+ * Each item carries its original index so the route handler can sort results
+ * back to input order after `Promise.all` resolves.
+ *
+ * @param items  Flat array of signal items as received in the request body.
+ * @returns      Array of groups; order of groups is not guaranteed, but item
+ *               order within each group is preserved.
+ */
+export declare function groupByAddressScanner(items: SignalItem[]): SignalGroup[];
+//# sourceMappingURL=group-by-scanner.d.ts.map

package/dist/runtime-api/handlers/group-by-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-by-scanner.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/handlers/group-by-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,iBAAiB,EAAE,CAAC;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,WAAW,EAAE,CAkBxE"}

package/dist/runtime-api/handlers/group-by-scanner.js

@@ -0,0 +1,43 @@
+/**
+ * Pure helper that groups a flat `SignalItem[]` by `(address, scanner)` so
+ * the route handler can fan-out groups in parallel while keeping items within
+ * a group sequential — dodging the per-(address, scanner) ingest lock held by
+ * `ScannerEngine` during async ingest
+ * (`src/scanners/engine/engine.ts:282-287`).
+ */
+/**
+ * Group signal items by `(lowercased address, scanner)`.
+ *
+ * Items within a group must be processed sequentially — the runtime's scanner
+ * engine holds a per-(address, scanner) mutex during the full async ingest
+ * chain and throws `UNAVAILABLE` on concurrent calls for the same key.
+ *
+ * Groups with different keys (different address or different scanner) can be
+ * processed in parallel — they do not share the lock.
+ *
+ * Each item carries its original index so the route handler can sort results
+ * back to input order after `Promise.all` resolves.
+ *
+ * @param items  Flat array of signal items as received in the request body.
+ * @returns      Array of groups; order of groups is not guaranteed, but item
+ *               order within each group is preserved.
+ */
+export function groupByAddressScanner(items) {
+    const grouped = new Map();
+    for (let index = 0; index < items.length; index++) {
+        const item = items[index];
+        // item is always defined inside bounds; the cast avoids a superfluous
+        // non-null assertion in strict mode.
+        const safeItem = item;
+        const key = `${safeItem.address.toLowerCase()}::${safeItem.scanner}`;
+        const existing = grouped.get(key);
+        if (existing !== undefined) {
+            existing.push({ index, item: safeItem });
+        }
+        else {
+            grouped.set(key, [{ index, item: safeItem }]);
+        }
+    }
+    return Array.from(grouped.values());
+}
+//# sourceMappingURL=group-by-scanner.js.map

package/dist/runtime-api/handlers/group-by-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-by-scanner.js","sourceRoot":"","sources":["../../../src/runtime-api/handlers/group-by-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAmB;IACvD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE/C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,sEAAsE;QACtE,qCAAqC;QACrC,MAAM,QAAQ,GAAG,IAAkB,CAAC;QACpC,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/dist/runtime-api/handlers/ingest-signals.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared ingest handler for `POST /signals`.
+ *
+ * Called by the HTTP route (S4) and the gateway-method shim (S6). Contains
+ * all business logic for one ingest item — lookup, validation, execution, and
+ * error translation — so neither transport duplicates logic.
+ */
+import type { SignalItem, SignalResult } from "./types.js";
+import type { RuntimeHandle } from "../../runtime/run.js";
+import type { Logger } from "../../utils/logger.js";
+/**
+ * Dependencies injected into {@link ingestSignalsHandler}.
+ *
+ * Keeping deps explicit (rather than closing over module-level state) makes
+ * unit-testing straightforward and keeps the function pure with respect to
+ * side effects outside the deps object.
+ */
+export interface IngestSignalsDeps {
+    /** Live runtime handles maintained by the plugin. */
+    runtimeHandles: Map<string, RuntimeHandle>;
+    /** Logger instance — errors logged at `error`, unexpected throws at `error`. */
+    logger: Logger;
+    /**
+     * Transport tag forwarded to future tracking events so the telemetry
+     * pipeline can distinguish HTTP-originated ingests from gateway-shim
+     * ingests on the migration dashboard.
+     */
+    transport: "http" | "gateway";
+}
+/**
+ * Ingest one signal item.
+ *
+ * Looks up the runtime by address, validates handler-level constraints, calls
+ * `RuntimeHandle.ingestExternalScannerData`, and translates all error shapes
+ * into the uniform `{ success: false, code, message }` discriminant. Never
+ * throws — all error paths return a `SignalResult`.
+ *
+ * Validation rules (beyond TypeBox):
+ * - At least one of `asset`, `data`, or `signals` must be present; an item
+ *   with none of those fields has nothing to ingest → `INVALID_REQUEST`.
+ * - `data` and `signals` are mutually exclusive → `INVALID_REQUEST`.
+ *   (The runtime also enforces this, but we check early to surface a clear
+ *   message before the engine lock is acquired.)
+ *
+ * Per-(address, scanner) ingest lock is the engine's concern; callers should
+ * use {@link groupByAddressScanner} or nest multiple signals in `signals[]`
+ * rather than submitting concurrent top-level items for the same key.
+ *
+ * @param item  A single element from the `POST /signals` request body.
+ * @param deps  Injected dependencies.
+ * @returns     A resolved `SignalResult` — never rejects.
+ */
+export declare function ingestSignalsHandler(item: SignalItem, deps: IngestSignalsDeps): Promise<SignalResult>;
+//# sourceMappingURL=ingest-signals.d.ts.map

package/dist/runtime-api/handlers/ingest-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-signals.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/handlers/ingest-signals.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC3C,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,YAAY,CAAC,CAuIvB"}

package/dist/runtime-api/handlers/ingest-signals.js

@@ -0,0 +1,141 @@
+/**
+ * Shared ingest handler for `POST /signals`.
+ *
+ * Called by the HTTP route (S4) and the gateway-method shim (S6). Contains
+ * all business logic for one ingest item — lookup, validation, execution, and
+ * error translation — so neither transport duplicates logic.
+ */
+import { ExternalScannerIngestError, } from "../../scanners/external-scanner-receiver.js";
+import { findRuntimeHandleByAddress } from "./lookup.js";
+/**
+ * Ingest one signal item.
+ *
+ * Looks up the runtime by address, validates handler-level constraints, calls
+ * `RuntimeHandle.ingestExternalScannerData`, and translates all error shapes
+ * into the uniform `{ success: false, code, message }` discriminant. Never
+ * throws — all error paths return a `SignalResult`.
+ *
+ * Validation rules (beyond TypeBox):
+ * - At least one of `asset`, `data`, or `signals` must be present; an item
+ *   with none of those fields has nothing to ingest → `INVALID_REQUEST`.
+ * - `data` and `signals` are mutually exclusive → `INVALID_REQUEST`.
+ *   (The runtime also enforces this, but we check early to surface a clear
+ *   message before the engine lock is acquired.)
+ *
+ * Per-(address, scanner) ingest lock is the engine's concern; callers should
+ * use {@link groupByAddressScanner} or nest multiple signals in `signals[]`
+ * rather than submitting concurrent top-level items for the same key.
+ *
+ * @param item  A single element from the `POST /signals` request body.
+ * @param deps  Injected dependencies.
+ * @returns     A resolved `SignalResult` — never rejects.
+ */
+export async function ingestSignalsHandler(item, deps) {
+    const address = item.address.toLowerCase();
+    const { scanner } = item;
+    // --- Handler-level validation ---
+    const hasAsset = item.asset !== undefined;
+    const hasData = item.data !== undefined;
+    // `signals: []` is treated as no signals — the caller intended a batch but
+    // sent nothing to ingest. Falls through to the at-least-one rule below.
+    const hasSignals = item.signals !== undefined && item.signals.length > 0;
+    if (!hasAsset && !hasData && !hasSignals) {
+        return {
+            success: false,
+            address,
+            scanner,
+            code: "INVALID_REQUEST",
+            message: "Signal item must include at least one of: asset, data, or signals.",
+        };
+    }
+    if (hasData && hasSignals) {
+        return {
+            success: false,
+            address,
+            scanner,
+            code: "INVALID_REQUEST",
+            message: "Signal item must not include both data and signals — they are mutually exclusive.",
+        };
+    }
+    // --- Runtime lookup ---
+    const lookup = findRuntimeHandleByAddress(deps.runtimeHandles, address);
+    if (!lookup.found) {
+        return {
+            success: false,
+            address,
+            scanner,
+            code: "NOT_FOUND",
+            message: lookup.message,
+        };
+    }
+    const { handle } = lookup;
+    // --- Build the ingest request (address stays at the routing layer) ---
+    //
+    // `signals` only forwarded when non-empty — mirrors the validation rule
+    // above. An empty array would have failed the at-least-one check (unless
+    // accompanied by asset/data), so we strip it here for symmetry: don't
+    // forward what the validator just rejected as meaningful payload.
+    const request = {
+        scanner: item.scanner,
+        ...(item.asset !== undefined && { asset: item.asset }),
+        ...(item.direction !== undefined && { direction: item.direction }),
+        ...(item.score !== undefined && { score: item.score }),
+        ...(item.signal_type !== undefined && { signal_type: item.signal_type }),
+        ...(item.data !== undefined && { data: item.data }),
+        ...(hasSignals && { signals: item.signals }),
+    };
+    // --- Dispatch ---
+    console.info("[senpi-runtime] [ingest-trace] /signals handler dispatching", JSON.stringify({
+        address,
+        scanner,
+        transport: deps.transport,
+        hasAsset,
+        hasData,
+        hasSignals,
+        dataKeys: hasData ? Object.keys(item.data) : [],
+    }));
+    try {
+        const result = await handle.ingestExternalScannerData(request);
+        // TODO(s11): emit runtime.signals_ingested with transport=deps.transport
+        console.info("[senpi-runtime] [ingest-trace] /signals handler dispatch ok", JSON.stringify({ address, scanner, signalCount: result.signalCount, contextUpdated: result.contextUpdated }));
+        return {
+            success: true,
+            address,
+            scanner,
+            timestamp: result.timestamp,
+            signalCount: result.signalCount,
+            contextUpdated: result.contextUpdated,
+        };
+    }
+    catch (err) {
+        console.info("[senpi-runtime] [ingest-trace] /signals handler dispatch THREW", JSON.stringify({
+            address,
+            scanner,
+            errType: err instanceof Error ? err.constructor.name : typeof err,
+            message: err instanceof Error ? err.message : String(err),
+        }));
+        if (err instanceof ExternalScannerIngestError) {
+            return {
+                success: false,
+                address,
+                scanner,
+                code: err.code,
+                message: err.message,
+            };
+        }
+        // Unexpected throw — do not add a new INTERNAL code; map to UNAVAILABLE
+        // per Section 5 plan: "reuse INVALID_REQUEST | NOT_FOUND | UNAVAILABLE".
+        const message = err instanceof Error
+            ? err.message
+            : `Unexpected ingest error: ${String(err)}`;
+        deps.logger.error("[senpi-core][runtime-api][ingest-signals] Unexpected error during ingest", { address, scanner, transport: deps.transport, err });
+        return {
+            success: false,
+            address,
+            scanner,
+            code: "UNAVAILABLE",
+            message,
+        };
+    }
+}
+//# sourceMappingURL=ingest-signals.js.map

package/dist/runtime-api/handlers/ingest-signals.js.map

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

package/dist/runtime-api/handlers/lookup.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure helper for resolving a running runtime handle by wallet address.
+ *
+ * Extracted from `getRuntimeHandleByAddressOrRespond` in `src/index.ts` so
+ * both the HTTP route layer (S4) and the gateway shim (S6) can share the
+ * lookup logic without the respond-on-error side-effect.
+ */
+import type { RuntimeHandle } from "../../runtime/run.js";
+/**
+ * Discriminated result of a handle lookup.
+ *
+ * Use `found` to narrow:
+ * - `true`  → `runtimeId` and `handle` are available.
+ * - `false` → `code` is always `"NOT_FOUND"` and `message` describes the miss.
+ */
+export type LookupResult = {
+    found: true;
+    runtimeId: string;
+    handle: RuntimeHandle;
+} | {
+    found: false;
+    code: "NOT_FOUND";
+    message: string;
+};
+/**
+ * Find a running runtime by lowercased wallet address.
+ *
+ * Matches case-insensitively — wallet addresses from the runtime's strategy
+ * config may differ in capitalisation from caller-supplied values.
+ *
+ * @param handles  The live map maintained by the plugin (`runtimeHandles`).
+ * @param address  Wallet address to search for. Case is normalised internally.
+ * @returns        A discriminated union; never throws.
+ */
+export declare function findRuntimeHandleByAddress(handles: Map<string, RuntimeHandle>, address: string): LookupResult;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/runtime-api/handlers/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/handlers/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACzD;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,OAAO,EAAE,MAAM,GACd,YAAY,CAYd"}

package/dist/runtime-api/handlers/lookup.js

@@ -0,0 +1,31 @@
+/**
+ * Pure helper for resolving a running runtime handle by wallet address.
+ *
+ * Extracted from `getRuntimeHandleByAddressOrRespond` in `src/index.ts` so
+ * both the HTTP route layer (S4) and the gateway shim (S6) can share the
+ * lookup logic without the respond-on-error side-effect.
+ */
+/**
+ * Find a running runtime by lowercased wallet address.
+ *
+ * Matches case-insensitively — wallet addresses from the runtime's strategy
+ * config may differ in capitalisation from caller-supplied values.
+ *
+ * @param handles  The live map maintained by the plugin (`runtimeHandles`).
+ * @param address  Wallet address to search for. Case is normalised internally.
+ * @returns        A discriminated union; never throws.
+ */
+export function findRuntimeHandleByAddress(handles, address) {
+    const normalizedAddress = address.toLowerCase();
+    for (const [runtimeId, handle] of handles) {
+        if (handle.wallet.toLowerCase() === normalizedAddress) {
+            return { found: true, runtimeId, handle };
+        }
+    }
+    return {
+        found: false,
+        code: "NOT_FOUND",
+        message: `No running runtime found for wallet address "${address}".`,
+    };
+}
+//# sourceMappingURL=lookup.js.map

package/dist/runtime-api/handlers/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../../src/runtime-api/handlers/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAmC,EACnC,OAAe;IAEf,MAAM,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAChD,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QAC1C,IAAI,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,iBAAiB,EAAE,CAAC;YACtD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,gDAAgD,OAAO,IAAI;KACrE,CAAC;AACJ,CAAC"}