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

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"}

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"}