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

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

@@ -0,0 +1,85 @@
+/**
+ * Transport-agnostic type definitions shared by all `src/runtime-api/handlers/`
+ * modules and the route layer that consumes them.
+ *
+ * No Fastify imports. No side-effects.
+ */
+import type { ExternalScannerIngestSignalItem, ExternalScannerIngestErrorCode } from "../../scanners/external-scanner-receiver.js";
+import type { Signal } from "../../scanners/types.js";
+/**
+ * Per-item shape accepted by `POST /signals`.
+ *
+ * Mirrors {@link ExternalScannerIngestRequest} with `address` lifted to the
+ * item level so a single request body can target multiple wallets.
+ *
+ * Only one of `data` (single-signal shortcut) or `signals[]` (batch within
+ * one address+scanner) may be present — the handler enforces mutual exclusion
+ * at runtime in addition to the TypeBox schema check.
+ */
+export interface SignalItem {
+    /** Wallet address of the target runtime. Lowercased server-side. */
+    address: string;
+    /** Configured scanner id. */
+    scanner: string;
+    /** Asset for a single ingested signal. */
+    asset?: string;
+    /** Direction for a single ingested signal. */
+    direction?: Signal["direction"];
+    /** Confidence score for a single ingested signal (0–1). */
+    score?: number;
+    /** Signal classification override for a single ingested signal. */
+    signal_type?: string;
+    /**
+     * Single ingest payload for signal-producing or context-producing scanners.
+     * Mutually exclusive with `signals[]`.
+     */
+    data?: Record<string, unknown>;
+    /**
+     * Batch signal payloads for signal-producing external scanners.
+     * Mutually exclusive with `data`.
+     * Prefer this over multiple top-level items for the same address+scanner
+     * to avoid the per-(address, scanner) ingest lock.
+     */
+    signals?: ExternalScannerIngestSignalItem[];
+}
+/**
+ * Per-item result returned by {@link ingestSignalsHandler}.
+ *
+ * INTERNAL handler shape — kept flat so the gateway shim
+ * (`senpi.ingestExternalScannerData` in `src/plugin.ts`) can read fields
+ * directly without a transform. The HTTP route layer
+ * (`routes/signals.ts`) reshapes this into the senpi-stack wire format
+ * `{ success, address, scanner, data | error }` before sending on the wire.
+ *
+ * Discriminator is `success` (matching MCP and the rest of the runtime-api
+ * surface).
+ *
+ * Error codes reuse the existing
+ * {@link ExternalScannerIngestErrorCode} taxonomy:
+ * `INVALID_REQUEST | NOT_FOUND | UNAVAILABLE`. No `INTERNAL` code is added —
+ * unexpected throws map to `UNAVAILABLE`.
+ */
+export type SignalResult = {
+    success: true;
+    /** Lowercased wallet address. */
+    address: string;
+    /** Configured scanner id. */
+    scanner: string;
+    /** Unix epoch ms timestamp from the ingest result. */
+    timestamp: number;
+    /** Number of committed signals; `0` for context-only ingests. */
+    signalCount: number;
+    /** Whether retained context was updated. */
+    contextUpdated: boolean;
+} | {
+    success: false;
+    /** Lowercased wallet address. */
+    address: string;
+    /** Configured scanner id. */
+    scanner: string;
+    /** Machine-readable failure code. */
+    code: ExternalScannerIngestErrorCode;
+    /** Human-readable failure detail. */
+    message: string;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/handlers/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,+BAA+B,EAC/B,8BAA8B,EAC/B,MAAM,6CAA6C,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAChC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,+BAA+B,EAAE,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,OAAO,EAAE,IAAI,CAAC;IACd,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,cAAc,EAAE,OAAO,CAAC;CACzB,GACD;IACE,OAAO,EAAE,KAAK,CAAC;IACf,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,EAAE,8BAA8B,CAAC;IACrC,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC"}

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

@@ -0,0 +1,8 @@
+/**
+ * Transport-agnostic type definitions shared by all `src/runtime-api/handlers/`
+ * modules and the route layer that consumes them.
+ *
+ * No Fastify imports. No side-effects.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/runtime-api/handlers/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/runtime-api/lifecycle.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Start/stop helpers for the runtime HTTP API.
+ *
+ * This module owns the Fastify server lifecycle: binding the port,
+ * flipping readiness states, and draining in-flight requests on shutdown
+ * with a hard 15s timeout so teardown always proceeds.
+ *
+ * The plugin glue layer (S6 in `src/index.ts`) calls {@link startApi} during
+ * `api.lifecycle.start` and {@link ApiHandle.close} during `api.lifecycle.stop`.
+ * This module does NOT modify `src/index.ts`.
+ */
+import type { FastifyInstance } from "fastify";
+import { type CreateApiDeps, type ApiArtifacts } from "./server.js";
+import type { Logger } from "../utils/logger.js";
+/**
+ * Hard timeout for Fastify drain.
+ *
+ * After this many milliseconds, {@link stopApi} logs a warning and proceeds
+ * to runtime teardown regardless of in-flight requests. 15s is enough
+ * headroom for any Telegram notification or close-resolver tick that may
+ * be mid-flight on the underlying runtime.
+ */
+export declare const DRAIN_HARD_TIMEOUT_MS = 15000;
+/**
+ * Handle returned by {@link startApi}.
+ *
+ * The plugin lifecycle layer holds this and calls `ready()` once runtimes
+ * are confirmed healthy, then `close()` at shutdown.
+ */
+export interface ApiHandle {
+    /** The bound Fastify instance (exposed for tests that need `fastify.inject`). */
+    fastify: FastifyInstance;
+    /**
+     * Flip readiness from `"starting"` to `"ok"`.
+     *
+     * Call immediately after {@link startApi} resolves unless you need a
+     * deliberate warm-up window before accepting traffic.
+     */
+    ready: () => void;
+    /**
+     * Drain in-flight requests and close the HTTP server.
+     *
+     * Sets readiness to `"draining"` (so `/health` starts returning 503),
+     * then awaits `fastify.close()` with a hard {@link DRAIN_HARD_TIMEOUT_MS}
+     * timeout. If the timeout fires, a warning is logged and teardown proceeds
+     * without waiting further.
+     *
+     * Never throws — all errors are logged and swallowed so the caller's
+     * teardown sequence is not interrupted.
+     */
+    close: () => Promise<void>;
+}
+/**
+ * Start the HTTP API server.
+ *
+ * Calls {@link createApi} to build the Fastify instance, binds it to
+ * `deps.apiConfig.host:deps.apiConfig.port`, and returns an {@link ApiHandle}.
+ *
+ * The server is NOT yet marked ready after this call — `/health` will return
+ * 503 until the caller invokes `handle.ready()`. Call `ready()` immediately
+ * after the runtimes are confirmed up, which in the plugin lifecycle is right
+ * after `startApi` returns.
+ *
+ * A boot-time warning is logged when `deps.apiConfig.host !== "127.0.0.1"` so
+ * any operator who opts into Docker port mapping sees it in the logs.
+ *
+ * @param deps  Same dependencies passed to {@link createApi}: runtime handles,
+ *              validated API config, logger, and plugin version string.
+ * @returns     An {@link ApiHandle} whose `ready()` and `close()` methods drive
+ *              the lifecycle.
+ * @throws      Re-throws any `fastify.listen()` error (e.g. `EADDRINUSE`) so
+ *              the plugin lifecycle layer can perform its rollback and fail the
+ *              openclaw start cleanly.
+ */
+export declare function startApi(deps: CreateApiDeps): Promise<ApiHandle>;
+/**
+ * Drain in-flight requests and close the HTTP server.
+ *
+ * Sets readiness to `"draining"` immediately so `/health` stops returning 200,
+ * then races `fastify.close()` against {@link DRAIN_HARD_TIMEOUT_MS}. If the
+ * hard timeout fires first, a warning is logged and a best-effort force-close
+ * is issued (fire-and-forget). The function always resolves — it never rejects.
+ *
+ * @param artifacts  The {@link ApiArtifacts} returned by `createApi`.
+ * @param logger     Logger for the startup/drain messages.
+ */
+declare function stopApi(artifacts: ApiArtifacts, logger: Logger): Promise<void>;
+/**
+ * Exported for tests (S8) so they can assert drain timeout behavior without
+ * going through the full `startApi` path.
+ *
+ * @internal  Not part of the public API surface — import only in `__tests__/`.
+ */
+export declare const __test_only: {
+    stopApi: typeof stopApi;
+};
+export {};
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/runtime-api/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/runtime-api/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAa,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,iFAAiF;IACjF,OAAO,EAAE,eAAe,CAAC;IACzB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CA+BtE;AAED;;;;;;;;;;GAUG;AACH,iBAAe,OAAO,CAAC,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD7E;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;CAAc,CAAC"}

package/dist/runtime-api/lifecycle.js

@@ -0,0 +1,137 @@
+/**
+ * Start/stop helpers for the runtime HTTP API.
+ *
+ * This module owns the Fastify server lifecycle: binding the port,
+ * flipping readiness states, and draining in-flight requests on shutdown
+ * with a hard 15s timeout so teardown always proceeds.
+ *
+ * The plugin glue layer (S6 in `src/index.ts`) calls {@link startApi} during
+ * `api.lifecycle.start` and {@link ApiHandle.close} during `api.lifecycle.stop`.
+ * This module does NOT modify `src/index.ts`.
+ */
+import { createApi } from "./server.js";
+/**
+ * Hard timeout for Fastify drain.
+ *
+ * After this many milliseconds, {@link stopApi} logs a warning and proceeds
+ * to runtime teardown regardless of in-flight requests. 15s is enough
+ * headroom for any Telegram notification or close-resolver tick that may
+ * be mid-flight on the underlying runtime.
+ */
+export const DRAIN_HARD_TIMEOUT_MS = 15_000;
+/**
+ * Start the HTTP API server.
+ *
+ * Calls {@link createApi} to build the Fastify instance, binds it to
+ * `deps.apiConfig.host:deps.apiConfig.port`, and returns an {@link ApiHandle}.
+ *
+ * The server is NOT yet marked ready after this call — `/health` will return
+ * 503 until the caller invokes `handle.ready()`. Call `ready()` immediately
+ * after the runtimes are confirmed up, which in the plugin lifecycle is right
+ * after `startApi` returns.
+ *
+ * A boot-time warning is logged when `deps.apiConfig.host !== "127.0.0.1"` so
+ * any operator who opts into Docker port mapping sees it in the logs.
+ *
+ * @param deps  Same dependencies passed to {@link createApi}: runtime handles,
+ *              validated API config, logger, and plugin version string.
+ * @returns     An {@link ApiHandle} whose `ready()` and `close()` methods drive
+ *              the lifecycle.
+ * @throws      Re-throws any `fastify.listen()` error (e.g. `EADDRINUSE`) so
+ *              the plugin lifecycle layer can perform its rollback and fail the
+ *              openclaw start cleanly.
+ */
+export async function startApi(deps) {
+    const artifacts = createApi(deps);
+    await artifacts.fastify.listen({
+        host: deps.apiConfig.host,
+        port: deps.apiConfig.port,
+    });
+    deps.logger.info("[runtime-api] api server started", {
+        host: deps.apiConfig.host,
+        port: deps.apiConfig.port,
+    });
+    // Friction is a feature: anyone who flips host to 0.0.0.0 sees this in logs.
+    if (deps.apiConfig.host !== "127.0.0.1") {
+        deps.logger.warn("[runtime-api] api.host is bound to \"" +
+            deps.apiConfig.host +
+            "\". " +
+            "The API is reachable from anything on this container's Docker network. " +
+            "If you set this for Postman testing, make sure your docker-compose port mapping " +
+            "uses the \"127.0.0.1:\" prefix so the API is not exposed beyond your laptop's loopback. " +
+            "See docs/runtime-docs/runtime-api.md \"Postman testing recipe\".");
+    }
+    return {
+        fastify: artifacts.fastify,
+        ready: () => artifacts.readiness.setOk(),
+        close: () => stopApi(artifacts, deps.logger),
+    };
+}
+/**
+ * Drain in-flight requests and close the HTTP server.
+ *
+ * Sets readiness to `"draining"` immediately so `/health` stops returning 200,
+ * then races `fastify.close()` against {@link DRAIN_HARD_TIMEOUT_MS}. If the
+ * hard timeout fires first, a warning is logged and a best-effort force-close
+ * is issued (fire-and-forget). The function always resolves — it never rejects.
+ *
+ * @param artifacts  The {@link ApiArtifacts} returned by `createApi`.
+ * @param logger     Logger for the startup/drain messages.
+ */
+async function stopApi(artifacts, logger) {
+    artifacts.readiness.setDraining();
+    // Capture the close promise once. Two reasons:
+    //   1. We need to mute its rejection unconditionally — when the drain
+    //      timeout wins the race, the close promise is still in flight and
+    //      may reject later, producing an unhandled rejection (the second
+    //      .close() call in the timeout branch was a *new* promise, not a
+    //      handler for the original).
+    //   2. We need a stable reference to race against the timeout below.
+    const closePromise = artifacts.fastify.close();
+    // Pre-attach a no-op catch so a late rejection on the original promise
+    // is always considered handled. The catch returns a new derived promise
+    // that we ignore — this does NOT prevent Promise.race below from seeing
+    // the rejection, since handlers on the same promise are independent.
+    closePromise.catch(() => { });
+    // Capture the timeout handle so we can clear it on the happy path.
+    // Otherwise, when fastify.close() wins the race, the still-pending
+    // setTimeout fires DRAIN_HARD_TIMEOUT_MS later and rejects an unwatched
+    // promise — an unhandled rejection on every clean shutdown.
+    let timeoutHandle;
+    try {
+        await Promise.race([
+            closePromise,
+            new Promise((_resolve, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error("DRAIN_TIMEOUT")), DRAIN_HARD_TIMEOUT_MS);
+            }),
+        ]);
+        logger.info("[runtime-api] api server stopped");
+    }
+    catch (err) {
+        if (err.message === "DRAIN_TIMEOUT") {
+            logger.warn("[runtime-api] api server drain exceeded hard timeout; proceeding to teardown", { timeoutMs: DRAIN_HARD_TIMEOUT_MS });
+            // The original closePromise is still in flight; any future rejection
+            // is already muted by the .catch() above. Caller proceeds to
+            // runtime teardown.
+            return;
+        }
+        // Unexpected close error — log and swallow so teardown sequence continues.
+        logger.error("[runtime-api] unexpected error during api server close", {
+            err,
+        });
+    }
+    finally {
+        // Always clear so the timeout cannot fire after stopApi returns.
+        if (timeoutHandle !== undefined) {
+            clearTimeout(timeoutHandle);
+        }
+    }
+}
+/**
+ * Exported for tests (S8) so they can assert drain timeout behavior without
+ * going through the full `startApi` path.
+ *
+ * @internal  Not part of the public API surface — import only in `__tests__/`.
+ */
+export const __test_only = { stopApi };
+//# sourceMappingURL=lifecycle.js.map

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

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

package/dist/runtime-api/readiness.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Three-state readiness contract for `GET /health`.
+ *
+ * S5 (lifecycle layer) wires the lifecycle to flip these states:
+ *  - `"starting"` — initial state; server is binding or warming up.
+ *  - `"ok"`       — server is bound and ready to handle traffic.
+ *  - `"draining"` — graceful-shutdown in progress; stop routing new requests.
+ *
+ * `GET /health` returns `200` for `"ok"` and `503` for the other two states
+ * so load balancers stop routing before the process exits.
+ */
+/** Three valid readiness states. */
+export type ReadinessState = "starting" | "ok" | "draining";
+/**
+ * Read-only interface consumed by `GET /health` and any other component that
+ * needs to observe readiness without being able to mutate it.
+ */
+export interface Readiness {
+    /** Return the current readiness state synchronously. */
+    state(): ReadinessState;
+}
+/**
+ * Create a mutable readiness object.
+ *
+ * The returned object satisfies both the read-only {@link Readiness} interface
+ * and exposes `setOk()` / `setDraining()` mutators for the lifecycle layer
+ * (S5) to call at the appropriate moments.
+ *
+ * Initial state is `"starting"`.
+ *
+ * @returns A combined readiness + mutator object.
+ */
+export declare function createReadiness(): Readiness & {
+    setOk(): void;
+    setDraining(): void;
+};
+//# sourceMappingURL=readiness.d.ts.map

package/dist/runtime-api/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/runtime-api/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oCAAoC;AACpC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,IAAI,GAAG,UAAU,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,KAAK,IAAI,cAAc,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,SAAS,GAAG;IAC7C,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,IAAI,IAAI,CAAC;CACrB,CAWA"}

package/dist/runtime-api/readiness.js

@@ -0,0 +1,35 @@
+/**
+ * Three-state readiness contract for `GET /health`.
+ *
+ * S5 (lifecycle layer) wires the lifecycle to flip these states:
+ *  - `"starting"` — initial state; server is binding or warming up.
+ *  - `"ok"`       — server is bound and ready to handle traffic.
+ *  - `"draining"` — graceful-shutdown in progress; stop routing new requests.
+ *
+ * `GET /health` returns `200` for `"ok"` and `503` for the other two states
+ * so load balancers stop routing before the process exits.
+ */
+/**
+ * Create a mutable readiness object.
+ *
+ * The returned object satisfies both the read-only {@link Readiness} interface
+ * and exposes `setOk()` / `setDraining()` mutators for the lifecycle layer
+ * (S5) to call at the appropriate moments.
+ *
+ * Initial state is `"starting"`.
+ *
+ * @returns A combined readiness + mutator object.
+ */
+export function createReadiness() {
+    let s = "starting";
+    return {
+        state: () => s,
+        setOk: () => {
+            s = "ok";
+        },
+        setDraining: () => {
+            s = "draining";
+        },
+    };
+}
+//# sourceMappingURL=readiness.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../../src/runtime-api/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe;IAI7B,IAAI,CAAC,GAAmB,UAAU,CAAC;IACnC,OAAO;QACL,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACd,KAAK,EAAE,GAAG,EAAE;YACV,CAAC,GAAG,IAAI,CAAC;QACX,CAAC;QACD,WAAW,EAAE,GAAG,EAAE;YAChB,CAAC,GAAG,UAAU,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,40 @@
+/**
+ * Fastify route: `GET /audit`.
+ *
+ * Proxies a `audit_query` MCP call through the runtime handle matching the
+ * requested wallet address. AbortSignal is wired to the HTTP request lifetime
+ * so MCP cancels in-flight work when the client disconnects.
+ *
+ * Business logic lives entirely in `handlers/audit.ts`. This file contains
+ * only Fastify wiring and query-string coercion.
+ */
+import type { FastifyInstance } from "fastify";
+import type { RuntimeHandle } from "../../runtime/run.js";
+import type { Logger } from "../../utils/logger.js";
+/**
+ * Dependencies injected into the `/audit` route at registration time.
+ */
+export interface AuditRouteDeps {
+    /** Live runtime handles maintained by the plugin, keyed by lowercased address. */
+    runtimeHandles: Map<string, RuntimeHandle>;
+    /** Logger instance for unexpected errors. */
+    logger: Logger;
+}
+/**
+ * Register `GET /audit` on the given Fastify instance.
+ *
+ * Coerces string query-string values to their typed counterparts before
+ * forwarding to `auditHandler`. The `success` field is `"true" | "false"` from
+ * the schema; converted to `boolean`. Integer fields are parsed with
+ * `parseInt`. Missing optional fields are left as `undefined`.
+ *
+ * HTTP status mapping from `AuditQueryError.code`:
+ *  - `NOT_FOUND` → 404
+ *  - `ABORTED`   → 504 (gateway timeout — client disconnected)
+ *  - `UPSTREAM`  → 502 (bad gateway — MCP error)
+ *
+ * @param fastify  Fastify instance to register the route on.
+ * @param deps     Route dependencies injected at plugin start.
+ */
+export declare function registerAuditRoute(fastify: FastifyInstance, deps: AuditRouteDeps): void;
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/routes/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC3C,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,cAAc,GACnB,IAAI,CAoEN"}

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

@@ -0,0 +1,90 @@
+/**
+ * Fastify route: `GET /audit`.
+ *
+ * Proxies a `audit_query` MCP call through the runtime handle matching the
+ * requested wallet address. AbortSignal is wired to the HTTP request lifetime
+ * so MCP cancels in-flight work when the client disconnects.
+ *
+ * Business logic lives entirely in `handlers/audit.ts`. This file contains
+ * only Fastify wiring and query-string coercion.
+ */
+import { AuditQuery } from "./audit.schema.js";
+import { auditHandler } from "../handlers/audit.js";
+/**
+ * Register `GET /audit` on the given Fastify instance.
+ *
+ * Coerces string query-string values to their typed counterparts before
+ * forwarding to `auditHandler`. The `success` field is `"true" | "false"` from
+ * the schema; converted to `boolean`. Integer fields are parsed with
+ * `parseInt`. Missing optional fields are left as `undefined`.
+ *
+ * HTTP status mapping from `AuditQueryError.code`:
+ *  - `NOT_FOUND` → 404
+ *  - `ABORTED`   → 504 (gateway timeout — client disconnected)
+ *  - `UPSTREAM`  → 502 (bad gateway — MCP error)
+ *
+ * @param fastify  Fastify instance to register the route on.
+ * @param deps     Route dependencies injected at plugin start.
+ */
+export function registerAuditRoute(fastify, deps) {
+    fastify.get("/audit", { schema: { querystring: AuditQuery } }, async (req, reply) => {
+        const q = req.query;
+        // Coerce string query-string values to typed handler args.
+        const args = {
+            ...(q.tool_name !== undefined && { tool_name: q.tool_name }),
+            ...(q.action_type !== undefined && { action_type: q.action_type }),
+            ...(q.success !== undefined && { success: q.success === "true" }),
+            ...(q.start_time !== undefined && { start_time: q.start_time }),
+            ...(q.end_time !== undefined && { end_time: q.end_time }),
+            ...(q.min_duration_ms !== undefined && {
+                min_duration_ms: parseInt(q.min_duration_ms, 10),
+            }),
+            ...(q.max_duration_ms !== undefined && {
+                max_duration_ms: parseInt(q.max_duration_ms, 10),
+            }),
+            ...(q.limit !== undefined
+                ? { limit: parseInt(q.limit, 10) }
+                : { limit: 100 }),
+            ...(q.offset !== undefined
+                ? { offset: parseInt(q.offset, 10) }
+                : { offset: 0 }),
+            ...(q.cursor_requested_at !== undefined && {
+                cursor_requested_at: q.cursor_requested_at,
+            }),
+            ...(q.cursor_id !== undefined && { cursor_id: q.cursor_id }),
+        };
+        // Wire AbortSignal to the request close event so MCP cancellation works
+        // when the HTTP client disconnects before the MCP response arrives.
+        const ac = new AbortController();
+        req.raw.on("close", () => {
+            if (req.raw.destroyed)
+                ac.abort();
+        });
+        const result = await auditHandler(q.address, args, deps, ac.signal);
+        if (result.success) {
+            // Spread MCP fields first, then explicit `address` / `strategyId` —
+            // ours take precedence if MCP ever introduces a colliding field name.
+            // Without this order, a future MCP schema bump could silently shadow
+            // our routing identifiers.
+            return reply.send({
+                success: true,
+                data: {
+                    ...result.result,
+                    address: result.address,
+                    strategyId: result.strategyId,
+                },
+            });
+        }
+        const statusMap = {
+            NOT_FOUND: 404,
+            ABORTED: 504,
+            UPSTREAM: 502,
+        };
+        const status = statusMap[result.code] ?? 502;
+        return reply.status(status).send({
+            success: false,
+            error: { code: result.code, message: result.message },
+        });
+    });
+}
+//# sourceMappingURL=audit.js.map

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

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

package/dist/runtime-api/routes/audit.schema.d.ts

@@ -0,0 +1,75 @@
+/**
+ * TypeBox schema for the `GET /audit` query string.
+ *
+ * All Fastify query-string values arrive as strings. Integer fields
+ * (`min_duration_ms`, `max_duration_ms`, `limit`, `offset`) and the `success`
+ * boolean are declared as strings here so TypeBox validation passes on the raw
+ * HTTP input. The route handler coerces them to the appropriate types before
+ * forwarding to `auditHandler`.
+ *
+ * Fields excluded from the caller-visible surface (per plan Section 6):
+ *  - `resource_type` — always `"strategy"`, set by `RuntimeHandle.auditQuery`.
+ *  - `resource_id`   — resolved wallet → strategyId, set by the handle.
+ *  - `user_ids`      — server-controlled (the MCP API-key user).
+ *  - `usernames`     — server-controlled (the MCP API-key user).
+ *
+ * @see senpi-hyperliquid-mcp/src/tools/audit.tools.ts `auditQueryInputSchema`
+ *   for the upstream MCP Zod schema this mirrors.
+ */
+import { type Static } from "@sinclair/typebox";
+/** TypeBox schema for `GET /audit` query-string parameters. */
+export declare const AuditQuery: import("@sinclair/typebox").TObject<{
+    /**
+     * Wallet address to scope the audit query.
+     * Required — used to look up the matching runtime handle.
+     */
+    address: import("@sinclair/typebox").TString;
+    /** Filter by exact tool name (e.g. `create_position`). */
+    tool_name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Filter by action classification.
+     * One of: `read`, `create`, `update`, `delete`.
+     */
+    action_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"read">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"update">, import("@sinclair/typebox").TLiteral<"delete">]>>;
+    /**
+     * Filter by success/failure.
+     * Query strings arrive as text — coerce `"true"` / `"false"` in the route.
+     */
+    success: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"true">, import("@sinclair/typebox").TLiteral<"false">]>>;
+    /** ISO 8601 inclusive lower bound on `requested_at`. */
+    start_time: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /** ISO 8601 inclusive upper bound on `requested_at`. */
+    end_time: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Minimum end-to-end duration in ms.
+     * Arrives as a string; pattern restricts to non-negative integers so
+     * `parseInt` never produces NaN. Coerced to integer in the route handler.
+     */
+    min_duration_ms: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Maximum end-to-end duration in ms.
+     * Arrives as a string; pattern restricts to non-negative integers so
+     * `parseInt` never produces NaN. Coerced to integer in the route handler.
+     */
+    max_duration_ms: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Page size (1–1000, MCP default 100).
+     * Arrives as a string; pattern restricts to non-negative integers.
+     * Coerced to integer in the route handler. Default `100` applied on
+     * missing value. MCP enforces the 1–1000 range.
+     */
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Offset-based pagination skip count (≥0, MCP default 0).
+     * Arrives as a string; pattern restricts to non-negative integers.
+     * Coerced to integer in the route handler.
+     */
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /** Cursor timestamp for keyset pagination (ISO 8601). Must pair with `cursor_id`. */
+    cursor_requested_at: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /** Cursor UUID for keyset pagination. Must pair with `cursor_requested_at`. */
+    cursor_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/** TypeScript type for the `GET /audit` query string. */
+export type AuditQueryT = Static<typeof AuditQuery>;
+//# sourceMappingURL=audit.schema.d.ts.map

package/dist/runtime-api/routes/audit.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.schema.d.ts","sourceRoot":"","sources":["../../../src/runtime-api/routes/audit.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEtD,+DAA+D;AAC/D,eAAO,MAAM,UAAU;IAEnB;;;OAGG;;IAGH,0DAA0D;;IAG1D;;;OAGG;;IAUH;;;OAGG;;IAKH,wDAAwD;;IAGxD,wDAAwD;;IAGxD;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;IAGH,qFAAqF;;IAGrF,+EAA+E;;EAIlF,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC"}