@aifight/aifight 0.1.0-alpha.1

package/dist/types/wsclient/client.d.ts

@@ -0,0 +1,220 @@
+import { type WSClientError } from "./errors";
+import { type ServerMessageEnvelope } from "./frame-handler";
+export interface WSWelcome {
+    readonly type: "welcome";
+    readonly data: {
+        readonly server_protocol_version: string;
+        readonly agent_id: string;
+        readonly agent_name: string;
+        readonly server_time: string;
+        readonly games: readonly string[];
+    };
+    readonly match_id?: string;
+}
+/**
+ * Discriminated union of valid outbound messages the client may
+ * `send()` to the server. Mirrors the four `client_*.schema.json`
+ * files at the TypeScript layer (rev 3 P2 #4 — TS first line of
+ * defence; ajv via `serializeClientMessage` is the authoritative
+ * runtime check).
+ *
+ * Required-vs-optional contracts here track schema `required` arrays:
+ *   - join_queue:    `data` required (game name lives here)
+ *   - leave_queue:   `data` optional (no fields needed)
+ *   - match_confirm: `data` required (carries confirm_id)
+ *   - action:        `match_id` required (server uses it for the
+ *                    per-player session_id) AND `data` required
+ *                    (the chosen action object)
+ *
+ * `match_id` on the three non-`action` types is envelope-level
+ * scaffolding — the schemas accept it but no current message uses it.
+ * Keep optional so callers don't have to thread an empty string.
+ *
+ * The `unknown` typing on `data` is deliberate: per-message strict
+ * payload typing is M1-22 codegen territory. ajv enforces the inner
+ * shape at runtime; surfacing it through TS now would duplicate
+ * conformance work.
+ */
+export type WSClientMessage = {
+    type: "join_queue";
+    data: unknown;
+    match_id?: string;
+} | {
+    type: "leave_queue";
+    data?: unknown;
+    match_id?: string;
+} | {
+    type: "match_confirm";
+    data: unknown;
+    match_id?: string;
+} | {
+    type: "action";
+    match_id: string;
+    data: unknown;
+} | {
+    type: "runtime_status";
+    data: unknown;
+    match_id?: string;
+};
+export interface WSClientOptions {
+    /** WebSocket URL — e.g. "wss://aifight.ai/api/ws" or
+     *  "ws://127.0.0.1:<port>/api/ws" in tests. */
+    url: string;
+    /** In-memory plaintext API key. Caller resolves from credentials.ts
+     *  (M1-05) before this call; transport never touches keychain. */
+    apiKey: string;
+    /** Runtime's compiled-in protocol version, SemVer (e.g. "1.0.0"
+     *  or "v1.0.0"). The optional "v" prefix is stripped before
+     *  comparison. Major component must match server's
+     *  server_protocol_version per plan §5.8 / ADR-016. */
+    expectedProtocolVersion: string;
+    /** Time after WS open() to receive the welcome frame. Default
+     *  10_000 ms. Tests can lower for fast-fail coverage. */
+    welcomeTimeoutMs?: number;
+    /** Client-initiated WS ping frame (opcode 0x9) interval in ms.
+     *  Default 25_000 (per plan §5.8 / ADR-015 — keeps server's
+     *  60s ReadDeadline safely fed). Set to 0 to DISABLE the
+     *  client-initiated ping entirely (the server's own ping +
+     *  the `ws` library's automatic pong reply still keep the
+     *  link alive in that case, but the structural Batch D fix
+     *  — independent client ping timer — is not active). */
+    pingIntervalMs?: number;
+    /** Optional caller-controlled AbortSignal. If pre-aborted
+     *  (signal.aborted=true at the moment createWSClient is called),
+     *  rejects synchronously with WSAbortedError. If aborted
+     *  mid-handshake, terminates the socket and rejects with
+     *  WSAbortedError. If aborted AFTER createWSClient resolves,
+     *  the WSClient transitions to "closed" (timers cleared,
+     *  socket terminated) — equivalent to calling close(); no
+     *  error is thrown since the signal owner is the actor. */
+    signal?: AbortSignal;
+}
+export type WSMessageHandler = (msg: ServerMessageEnvelope) => void | Promise<void>;
+/** Frame-level errors surfaced AFTER createWSClient resolves —
+ *  malformed inbound JSON, schema violations, unknown server
+ *  message types. Connect / handshake / welcome errors are
+ *  rejected by createWSClient itself and never reach onError. */
+export type WSErrorHandler = (err: WSClientError) => void | Promise<void>;
+/** Information passed to onClose handlers. The connection is
+ *  fully torn down by the time this fires; no further onMessage
+ *  / onError handlers will run. */
+export interface WSCloseInfo {
+    /** WS close code from the close frame, or 0 for synthetic
+     *  closes (abort, transport error before close frame). */
+    readonly code: number;
+    /** Human-readable reason. For client-initiated close, the
+     *  string passed to close(); for server-initiated, what the
+     *  server sent; for abort, the constant "aborted". */
+    readonly reason: string;
+    /** Who initiated the close: client (close() call), server
+     *  (server-side close), or abort (AbortSignal fired
+     *  post-connect). */
+    readonly initiator: "client" | "server" | "abort";
+}
+export type WSCloseHandler = (info: WSCloseInfo) => void | Promise<void>;
+/** @internal — passed from createWSClient to WSClientImpl constructor. */
+interface WSClientInternalOpts {
+    pingIntervalMs?: number;
+    signal?: AbortSignal;
+}
+declare class WSClientImpl {
+    #private;
+    /** The authenticated welcome frame received from the server. */
+    readonly welcome: WSWelcome;
+    /**
+     * Constructor is REACHABLE only from this module's createWSClient
+     * factory. Because WSClientImpl is not exported, consumers of
+     * @aifight/aifight cannot `new` it (they only see the
+     * `export type WSClient = WSClientImpl` alias, which carries
+     * no constructor signature). The `socket` parameter is typed as
+     * `unknown` belt-and-suspenders so that even if an internal
+     * caller someday passes the wrong shape it fails as a cast
+     * mistake rather than a structural type leak.
+     *
+     * Step 5a additions:
+     *   - Starts a client-initiated ping timer (default 25s; pass
+     *     pingIntervalMs=0 to disable).
+     *   - Wires opts.signal so a post-connect abort triggers a forced
+     *     close-equivalent transition (state→closed, timer cleared,
+     *     socket terminated) without throwing — the signal owner is
+     *     the actor and already knows.
+     *
+     * Step 5b1 additions:
+     *   - Re-attaches "message", "error", "close" listeners on the
+     *     socket (createWSClient's cleanup() removed all listeners
+     *     during the handshake settle; this is the post-handshake
+     *     re-attachment Roy flagged in the Step 5b1 brief).
+     *   - "message" routes through parseServerFrame and dispatches
+     *     to onMessage / onError handlers.
+     *   - "close" emits onClose (idempotent via #closeDispatched).
+     *   - "error" goes to a silent sink; transport errors usually
+     *     pair with "close" which carries the user-facing signal.
+     *     Frame-level errors (parse / schema / unknown) come through
+     *     the message path, not the error event.
+     */
+    constructor(socket: unknown, welcome: WSWelcome, opts: WSClientInternalOpts);
+    /** Current lifecycle state. Step 5b1 expanded to three values:
+     *  "connected" after createWSClient resolves, "closing" while
+     *  close() is awaiting the socket close handshake (briefly),
+     *  "closed" after close completes (or abort / server close
+     *  fires). M1-07 may add "reconnecting". */
+    get state(): "connected" | "closing" | "closed";
+    onMessage(handler: WSMessageHandler): () => void;
+    onError(handler: WSErrorHandler): () => void;
+    onClose(handler: WSCloseHandler): () => void;
+    /**
+     * Send an outbound message to the server. Synchronous.
+     *
+     * @throws {WSClosedError} when the client is not in the "connected"
+     *         state (i.e. close()/abort/server-close has fired).
+     * @throws {WSOutboundSchemaError} when `msg` fails ajv validation
+     *         against client_<type>.schema.json. The error carries the
+     *         offending message type and the raw ajv error array.
+     */
+    send(msg: WSClientMessage): void;
+    /**
+     * Initiate a clean WS close. State transitions
+     * connected → closing → closed; onClose fires exactly once when
+     * the socket's "close" event arrives.
+     *
+     * Idempotent semantics:
+     *   - Calling on a "closing" instance returns the in-flight
+     *     close promise (so two awaiters share the same await).
+     *   - Calling on a "closed" instance returns immediately.
+     *   - Subsequent call after either resolves does nothing.
+     */
+    close(code?: number, reason?: string): Promise<void>;
+}
+/** The public WSClient type. This is a type alias over the internal
+ *  WSClientImpl class — consumers can use `WSClient` as a TypeScript
+ *  type (parameter / return / variable annotation) but cannot
+ *  construct one directly because no class value with this name is
+ *  exported. The only way to obtain a WSClient is via the
+ *  createWSClient() factory. */
+export type WSClient = WSClientImpl;
+/**
+ * Open a WebSocket to `opts.url`, send `X-API-Key` in the upgrade
+ * request, wait for the server's welcome frame, validate it
+ * (ajv + protocol-version major), and return a WSClient bound to
+ * the open socket.
+ *
+ * Resolves on welcome accepted. Rejects with one of:
+ *   - WSConnectError         — TCP/TLS/DNS failure (no HTTP response)
+ *   - WSHandshakeError       — HTTP upgrade returned non-101 (4xx/5xx)
+ *   - WSWelcomeTimeoutError  — open succeeded but no frame within
+ *                              welcomeTimeoutMs (default 10s)
+ *   - WSWelcomeInvalidError  — first frame is not a valid welcome:
+ *                              malformed JSON, unknown type,
+ *                              wrong type, or schema-invalid welcome
+ *                              (ajv errors carried)
+ *   - WSProtocolVersionError — welcome valid but
+ *                              server_protocol_version major
+ *                              differs from expectedProtocolVersion
+ *
+ * Step 4 caveats:
+ *   - No AbortSignal (Step 5).
+ *   - No reconnect (M1-07).
+ *   - No retry on any error class — caller decides.
+ */
+export declare function createWSClient(opts: WSClientOptions): Promise<WSClient>;
+export {};

package/dist/types/wsclient/errors.d.ts

@@ -0,0 +1,106 @@
+export interface AjvLikeError {
+    readonly instancePath: string;
+    readonly message?: string;
+}
+export type WSClientErrorKind = "connect" | "handshake" | "welcome-timeout" | "welcome-invalid" | "protocol-version" | "closed" | "schema" | "outbound-schema" | "unknown-message" | "aborted";
+export declare abstract class WSClientError extends Error {
+    abstract readonly kind: WSClientErrorKind;
+}
+/** TCP / TLS / DNS layer failure: the WebSocket couldn't even
+ *  reach the HTTP upgrade step. Wraps the underlying Node net /
+ *  tls / dns error (or whatever the `ws` library surfaced). */
+export declare class WSConnectError extends WSClientError {
+    readonly kind: "connect";
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/** HTTP upgrade was attempted and the server replied with an error
+ *  status (typically 401 invalid api key, 404 wrong path, 5xx
+ *  server fault). `responseBody` is the raw response payload as a
+ *  string; callers SHOULD NOT JSON.parse it without checking
+ *  Content-Type, since some 5xx pages are HTML. */
+export declare class WSHandshakeError extends WSClientError {
+    readonly kind: "handshake";
+    readonly statusCode: number;
+    readonly responseBody: string;
+    readonly cause?: unknown;
+    constructor(statusCode: number, responseBody: string, message: string, cause?: unknown);
+}
+/** WS open succeeded but no frame arrived within
+ *  `welcomeTimeoutMs` (default 10s). Distinguished from
+ *  WSConnectError so callers can differentiate "couldn't reach
+ *  server" from "reached server but it's not speaking". */
+export declare class WSWelcomeTimeoutError extends WSClientError {
+    readonly kind: "welcome-timeout";
+    constructor(message: string);
+}
+/** First server frame arrived but is not a valid welcome — wrong
+ *  type, malformed JSON, or fails ajv against
+ *  server_welcome.schema.json. `ajvErrors` is the raw ajv error
+ *  array (or empty for non-ajv failures like "wrong type"). */
+export declare class WSWelcomeInvalidError extends WSClientError {
+    readonly kind: "welcome-invalid";
+    readonly ajvErrors: readonly AjvLikeError[];
+    constructor(ajvErrors: readonly AjvLikeError[], message: string);
+}
+/** server_protocol_version's major component does not match the
+ *  runtime's compiled-in expectedProtocolVersion. Per plan §5.8 +
+ *  server_welcome.schema.json the runtime MUST refuse such
+ *  connections (major bumps are breaking). Minor / patch
+ *  mismatches do NOT throw this — they are silently accepted. */
+export declare class WSProtocolVersionError extends WSClientError {
+    readonly kind: "protocol-version";
+    readonly clientVersion: string;
+    readonly serverVersion: string;
+    constructor(clientVersion: string, serverVersion: string, message: string);
+}
+/** Operation attempted on a WSClient whose state is not
+ *  "connected": send() during closing, send() after close,
+ *  close() called twice (this is no-op, not an error — but
+ *  internal use may distinguish). */
+export declare class WSClosedError extends WSClientError {
+    readonly kind: "closed";
+    constructor(message: string);
+}
+/** Inbound frame failed ajv validation against its
+ *  per-message schema. Indicates server bug or protocol drift —
+ *  surfaced to onError handler; the connection stays open and
+ *  the offending message is dropped. `messageType` is the
+ *  envelope's `type` field if parseable, else "<unknown>". */
+export declare class WSSchemaError extends WSClientError {
+    readonly kind: "schema";
+    readonly messageType: string;
+    readonly ajvErrors: readonly AjvLikeError[];
+    constructor(messageType: string, ajvErrors: readonly AjvLikeError[], message: string);
+}
+/** Outbound message passed to send() failed ajv validation
+ *  against the matching client_*.schema.json. Indicates LOCAL
+ *  code bug (we tried to send something the server would
+ *  reject) — thrown synchronously to the calling code, message
+ *  never reaches the wire. Kept distinct from WSSchemaError
+ *  because callers MUST treat it as a programming error, not a
+ *  runtime drift signal. */
+export declare class WSOutboundSchemaError extends WSClientError {
+    readonly kind: "outbound-schema";
+    readonly messageType: string;
+    readonly ajvErrors: readonly AjvLikeError[];
+    constructor(messageType: string, ajvErrors: readonly AjvLikeError[], message: string);
+}
+/** Inbound frame's `type` field is not in the dispatch table
+ *  (see protocol/schemas.ts MESSAGE_TYPE_TO_FILE). Server bug
+ *  or version skew — surfaced to onError, message dropped,
+ *  connection stays open. */
+export declare class WSUnknownMessageError extends WSClientError {
+    readonly kind: "unknown-message";
+    readonly messageType: string;
+    constructor(messageType: string, message: string);
+}
+/** The caller-controlled AbortSignal fired during connect() or a
+ *  mid-flight operation. `cause` carries the abort reason
+ *  (AbortSignal.reason) so callers can distinguish their own
+ *  abort categories without parsing message text. */
+export declare class WSAbortedError extends WSClientError {
+    readonly kind: "aborted";
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}

package/dist/types/wsclient/frame-handler.d.ts

@@ -0,0 +1,20 @@
+export interface ClientMessageEnvelope {
+    type: string;
+    data?: unknown;
+    /** REQUIRED for type=action (per client_action.schema.json), optional otherwise. */
+    match_id?: string;
+}
+export interface ServerMessageEnvelope {
+    type: string;
+    data: unknown;
+    match_id?: string;
+}
+/** Warm the ajv cache up-front. Optional — getAjv() is lazy and
+ *  serializeClientMessage / parseServerFrame call it on first use. */
+export declare function initFrameHandler(): void;
+/** Test-only: drop the ajv singleton so the next getAjv() call
+ *  rewalks loadAllSchemas(). Pairs with __resetSchemasRootCache()
+ *  in protocol/schemas.ts. NOT exported from src/index.ts. */
+export declare function __resetFrameHandlerCache(): void;
+export declare function serializeClientMessage(msg: ClientMessageEnvelope): string;
+export declare function parseServerFrame(raw: string | Buffer): ServerMessageEnvelope;

package/dist/types/wsclient/reconnect.d.ts

@@ -0,0 +1,84 @@
+import { type WSClientMessage, type WSWelcome, type WSMessageHandler, type WSErrorHandler } from "./client";
+import { WSClientError } from "./errors";
+/** Reasons the reconnect facade can transition to terminal "closed" state.
+ *  ReconnectCloseInfo.kind and ReconnectStoppedError.kind share this union —
+ *  5 values used consistently across onClose handler, give-up event, and
+ *  cause chain (rev 2 Codex C4). */
+export type ReconnectStopReason = "caller-close" | "signal" | "fatal-close" | "fatal-error" | "max-attempts";
+/** Inline error class — reconnect's own final-state error. Lives at the top
+ *  of reconnect.ts, NOT in wsclient/errors.ts (scope fence #1).
+ *  rev 2 Codex C4: renamed from ReconnectAbortedError to ReconnectStoppedError. */
+export declare class ReconnectStoppedError extends Error {
+    readonly name = "ReconnectStoppedError";
+    readonly kind: ReconnectStopReason;
+    readonly cause: WSClientError | undefined;
+    constructor(kind: ReconnectStopReason, cause: WSClientError | undefined, message: string);
+}
+/** Terminal-close info passed to facade.onClose handler (rev 2 Codex C3).
+ *  NOT a re-use of M1-06 WSCloseInfo — facade close semantics are wider than
+ *  a single WS close frame. **No wasClean field** (M1-06 WSCloseInfo also
+ *  doesn't have one; rev 1 wrote it incorrectly, rev 2 removed). */
+export interface ReconnectCloseInfo {
+    readonly kind: ReconnectStopReason;
+    readonly code?: number;
+    readonly closeReason?: string;
+    readonly cause?: WSClientError | ReconnectStoppedError;
+}
+export type ReconnectCloseHandler = (info: ReconnectCloseInfo) => void;
+/** Backoff jitter strategy. Default "full" (rev 2 Roy 拍板 #2). */
+export type JitterStrategy = "none" | "full" | "equal";
+export interface ReconnectingWSClientOptions {
+    url: string;
+    apiKey: string;
+    expectedProtocolVersion: string;
+    initialBackoffMs?: number;
+    backoffFactor?: number;
+    maxBackoffMs?: number;
+    jitter?: JitterStrategy;
+    /** Default: undefined → no cap (Roy 拍板 #3). Caller controls termination
+     *  via signal + AbortController.abort(timeoutMs). */
+    maxAttempts?: number;
+    welcomeTimeoutMs?: number;
+    pingIntervalMs?: number;
+    signal?: AbortSignal;
+}
+export interface ReconnectEvent {
+    readonly type: "attempt-start" | "attempt-success" | "attempt-failure" | "give-up";
+    readonly attempt: number;
+    readonly nextDelayMs?: number;
+    readonly cause?: WSClientError | ReconnectStoppedError;
+    readonly elapsedMs: number;
+    readonly severity: "info" | "warning" | "error";
+}
+export type ReconnectEventHandler = (ev: ReconnectEvent) => void;
+/** Stable facade — caller holds this reference indefinitely. Inner WSClient
+ *  is mutable across reconnects; facade type is stable. */
+export interface ReconnectingWSClient {
+    readonly state: "connecting" | "connected" | "backoff" | "closed";
+    readonly attempt: number;
+    readonly welcome: WSWelcome | null;
+    send(msg: WSClientMessage): void;
+    onMessage(handler: WSMessageHandler): () => void;
+    onError(handler: WSErrorHandler): () => void;
+    onClose(handler: ReconnectCloseHandler): () => void;
+    onReconnect(handler: ReconnectEventHandler): () => void;
+    close(code?: number, reason?: string): Promise<void>;
+}
+/**
+ * Open a reconnecting WebSocket session. Returns a Promise that:
+ *
+ *   - **resolves** on the FIRST inner WSClient connect+welcome success
+ *   - **rejects** with ReconnectStoppedError on fatal first failure (signal
+ *     pre-aborted / WSHandshakeError 401|403|404 / WSWelcomeInvalidError /
+ *     WSProtocolVersionError / WSAbortedError / max-attempts during the
+ *     first-connect retry chain)
+ *   - **stays pending** while transient first failures (WSConnectError /
+ *     WSWelcomeTimeoutError / WSHandshakeError 408|429|5xx) drive backoff
+ *     and re-attempt, until a success or fatal terminator
+ *
+ * After the Promise resolves, the returned facade survives across server
+ * disconnects: inner WSClient close → backoff → new createWSClient →
+ * handlers re-wired. Caller's onMessage / onError / onClose / onReconnect
+ * handlers persist across reconnects automatically.
+ */
+export declare function createReconnectingWSClient(opts: ReconnectingWSClientOptions): Promise<ReconnectingWSClient>;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@aifight/aifight",
+  "version": "0.1.0-alpha.1",
+  "description": "AIFight CLI — local outbound bridge that connects AIFight to user-selected Agent runtimes.",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "aifight": "dist/bin.mjs",
+    "aifight-bridge": "dist/bin.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "7.6.13",
+    "@types/node": "^22.10.0",
+    "@types/ws": "8.18.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "ws": "8.20.0"
+  },
+  "scripts": {
+    "build": "./build.sh",
+    "gen:schema": "node scripts/bundle-schema.mjs",
+    "pack:check": "node scripts/verify-packlist.mjs",
+    "prepublishOnly": "npm run build && npm run pack:check",
+    "test": "npm run gen:schema && vitest run",
+    "check-types": "npm run gen:schema && tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@napi-rs/keyring": "1.2.0",
+    "better-sqlite3": "12.9.0"
+  }
+}