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

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

@@ -1,134 +0,0 @@
-/**
- * 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;
-    const hasSignals = item.signals !== undefined;
-    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) ---
-    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 }),
-        ...(item.signals !== undefined && { 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

@@ -1 +0,0 @@
-{"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

@@ -1,36 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,31 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,80 +0,0 @@
-/**
- * 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}.
- *
- * Uses `success` (not `ok`) — this is the per-item signal shape (Section 5 of
- * the plan). The `/audit` handler uses `ok` because it is a single-resource
- * HTTP response, not a fan-out array result.
- *
- * 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

@@ -1 +0,0 @@
-{"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;;;;;;;;;;;GAWG;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

@@ -1,8 +0,0 @@
-/**
- * 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

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

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

@@ -1,98 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,137 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/runtime-api/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,SAAS,EAAyC,MAAM,aAAa,CAAC;AAG/E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAgC5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAmB;IAChD,MAAM,SAAS,GAAiB,SAAS,CAAC,IAAI,CAAC,CAAC;IAEhD,MAAM,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;QACzB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;KAC1B,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kCAAkC,EAAE;QACnD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;QACzB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;KAC1B,CAAC,CAAC;IAEH,6EAA6E;IAC7E,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,uCAAuC;YACrC,IAAI,CAAC,SAAS,CAAC,IAAI;YACnB,MAAM;YACN,yEAAyE;YACzE,kFAAkF;YAClF,0FAA0F;YAC1F,kEAAkE,CACrE,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE;QACxC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,KAAK,UAAU,OAAO,CAAC,SAAuB,EAAE,MAAc;IAC5D,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;IAElC,+CAA+C;IAC/C,sEAAsE;IACtE,uEAAuE;IACvE,sEAAsE;IACtE,sEAAsE;IACtE,kCAAkC;IAClC,qEAAqE;IACrE,MAAM,YAAY,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC/C,uEAAuE;IACvE,wEAAwE;IACxE,wEAAwE;IACxE,qEAAqE;IACrE,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAE7B,mEAAmE;IACnE,mEAAmE;IACnE,wEAAwE;IACxE,4DAA4D;IAC5D,IAAI,aAAwD,CAAC;IAE7D,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAAC;YACjB,YAAY;YACZ,IAAI,OAAO,CAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;gBACrC,aAAa,GAAG,UAAU,CACxB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC,EACxC,qBAAqB,CACtB,CAAC;YACJ,CAAC,CAAC;SACH,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAAa,CAAC,OAAO,KAAK,eAAe,EAAE,CAAC;YAC/C,MAAM,CAAC,IAAI,CACT,8EAA8E,EAC9E,EAAE,SAAS,EAAE,qBAAqB,EAAE,CACrC,CAAC;YACF,qEAAqE;YACrE,6DAA6D;YAC7D,oBAAoB;YACpB,OAAO;QACT,CAAC;QACD,2EAA2E;QAC3E,MAAM,CAAC,KAAK,CAAC,wDAAwD,EAAE;YACrE,GAAG;SACJ,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,iEAAiE;QACjE,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAChC,YAAY,CAAC,aAAa,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,OAAO,EAAE,CAAC"}

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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,35 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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"}