@aifight/aifight 0.1.0-alpha.1

package/dist/types/daemon/lifecycle.d.ts

@@ -0,0 +1,85 @@
+import { type AgentRow } from "../store/sqlite";
+import type { DailyScheduleConfig } from "../scheduler/types";
+import { type ControlLogEvent } from "../controlapi/types";
+import type { StrategyProfile } from "../decision/types";
+import { buildConnectWithGameStartCache } from "./agent-decision-adapter";
+export interface DaemonOptions {
+    /** Default "127.0.0.1". Plan ADR-013 locks to loopback in M1; daemon
+     *  validates in cli/commands/serve.ts (Step 3 wires --host argv). */
+    readonly host?: string;
+    /** Default 0 — OS picks an unused port. Resolved bound port surfaces
+     *  on `DaemonHandle.bound.port`. */
+    readonly port?: number;
+    readonly onLog?: (event: DaemonLogEvent) => void;
+    readonly testHooks?: DaemonTestHooks;
+}
+export type DaemonLogLevel = "info" | "warn" | "error";
+export type DaemonLogCode = "lock_acquired" | "agents_loaded" | "control_server_listening" | "runtime_files_written" | "daemon_ready" | "signal_received" | "shutdown_initiated" | "shutdown_completed" | "shutdown_forced" | "agent_load_failed" | "agent_skipped_turn" | "control_server_proxy" | "lock_release_failed" | "tmp_cleanup_failed";
+export interface DaemonLogEvent {
+    readonly level: DaemonLogLevel;
+    readonly code: DaemonLogCode;
+    readonly message: string;
+    readonly cause?: unknown;
+    /** Only set when `code === "control_server_proxy"` — forwarded
+     *  M1-16 ControlLogEvent payload. */
+    readonly controlEvent?: ControlLogEvent;
+}
+export interface DaemonTestHooks {
+    /** Override timer functions (force-exit timer, etc). */
+    readonly setTimeout?: typeof globalThis.setTimeout;
+    readonly clearTimeout?: typeof globalThis.clearTimeout;
+    /** Override process.on signal subscription. Default attaches to
+     *  process; tests inject a fake emitter so signals can be simulated
+     *  without sending real SIGINT to the test runner. The returned
+     *  function detaches the listener. */
+    readonly onSignal?: (sig: NodeJS.Signals, listener: () => void) => () => void;
+    /** Override `process.exit`. Production path uses `process.exit`;
+     *  tests inject a recorder so the test runner is never killed. Used
+     *  only on force-exit / second-signal paths (rev3 fix #3). */
+    readonly exit?: (code: number) => void;
+    /** Override agent row loading. Production reads SQLite via
+     *  openDatabase().listAgents(). Tests inject fixtures without a real
+     *  DB. */
+    readonly loadAgents?: () => readonly AgentRow[];
+    /** Override strategy profile loading. Production reads
+     *  `getRuntimeHome()/agents/<name>/strategy.json` (post-Step-2 path
+     *  detail; Step 2 minimum is testHook-driven and tests inject
+     *  fixtures). Throw to trigger per-agent skip. */
+    readonly loadStrategy?: (agentName: string) => StrategyProfile;
+    /** Override daily-schedule config loading. Returning null = no
+     *  scheduler. */
+    readonly loadDailyConfig?: (agentName: string) => DailyScheduleConfig | null;
+    /** Override `os.platform()` for case 26 (Windows SIGTERM omission). */
+    readonly platform?: NodeJS.Platform;
+    /** Override the wsclient connect factory used by AgentInstance.
+     *  Default = `createReconnectingWSClient` from M1-07. Tests inject
+     *  to capture wsclient options (asserts apiKey === platformKey, etc)
+     *  without opening a real socket. */
+    readonly wsConnectFactory?: Parameters<typeof buildConnectWithGameStartCache>[1];
+    /** Force-exit timeout in ms. Default 30000 (TED 拍板点 #7).
+     *  Tests use a small value (e.g. 50ms) to validate timeout behavior
+     *  without making the suite slow. */
+    readonly forceExitTimeoutMs?: number;
+}
+export type ShutdownReason = {
+    readonly source: "signal";
+    readonly signal: NodeJS.Signals;
+} | {
+    readonly source: "control_api";
+} | {
+    readonly source: "startup_failure";
+    readonly cause: unknown;
+};
+export interface DaemonHandle {
+    readonly bound: {
+        readonly host: string;
+        readonly port: number;
+    };
+    /** Idempotent — second call returns the same promise as the first. */
+    requestShutdown(reason: ShutdownReason): Promise<number>;
+    /** Long-lived completion. Resolves with the final exit code; never
+     *  rejects. runServe() awaits this to keep the foreground process
+     *  alive (rev2 fix #1). */
+    readonly closed: Promise<number>;
+}
+export declare function startDaemon(opts?: DaemonOptions): Promise<DaemonHandle>;

package/dist/types/daemon/router.d.ts

@@ -0,0 +1,97 @@
+import type { AgentInstanceSnapshot } from "../agents/agent";
+export interface RouterAgentConfig {
+    readonly name: string;
+    readonly id?: string;
+    readonly enabled?: boolean;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface RouterAgentRuntime {
+    start(): Promise<AgentInstanceSnapshot>;
+    stop(reason?: string): Promise<void>;
+    joinQueue(game: string, mode?: string, opts?: {
+        readonly oneShot?: boolean;
+        readonly count?: number;
+    }): void;
+    leaveQueue(): void;
+    confirmMatch(confirmId?: string): void;
+    snapshot(): AgentInstanceSnapshot;
+    onState(handler: (snapshot: AgentInstanceSnapshot) => void): () => void;
+}
+export type RouterAgentFactory = (config: RouterAgentConfig) => RouterAgentRuntime;
+export type RouterAgentSelector = string | {
+    readonly name?: string;
+    readonly id?: string;
+};
+export interface RouterSnapshot {
+    readonly agents: readonly AgentInstanceSnapshot[];
+}
+export interface MultiAgentRouterOptions {
+    readonly agents?: readonly RouterAgentConfig[];
+    readonly agentFactory: RouterAgentFactory;
+    readonly onNotify?: (event: RouterNotifyEvent) => void;
+}
+export interface RouterNotifyEvent {
+    readonly level: "info" | "warning" | "error";
+    readonly code: string;
+    readonly message: string;
+    readonly agent?: string;
+    readonly cause?: unknown;
+}
+export type RouterErrorKind = "router_duplicate_agent" | "router_agent_not_found" | "router_selector_mismatch" | "router_agent_factory" | "router_agent_lifecycle";
+export declare abstract class RouterError extends Error {
+    abstract readonly kind: RouterErrorKind;
+    readonly cause: unknown;
+    protected constructor(message: string, cause?: unknown);
+}
+export declare class RouterDuplicateAgentError extends RouterError {
+    readonly name = "RouterDuplicateAgentError";
+    readonly kind: "router_duplicate_agent";
+    readonly field: "name" | "id";
+    readonly value: string;
+    constructor(field: "name" | "id", value: string);
+}
+export declare class RouterAgentNotFoundError extends RouterError {
+    readonly name = "RouterAgentNotFoundError";
+    readonly kind: "router_agent_not_found";
+    readonly selector: RouterAgentSelector;
+    constructor(selector: RouterAgentSelector);
+}
+export declare class RouterSelectorMismatchError extends RouterError {
+    readonly name = "RouterSelectorMismatchError";
+    readonly kind: "router_selector_mismatch";
+    readonly nameSelector: string;
+    readonly idSelector: string;
+    constructor(nameSelector: string, idSelector: string);
+}
+export declare class RouterAgentFactoryError extends RouterError {
+    readonly name = "RouterAgentFactoryError";
+    readonly kind: "router_agent_factory";
+    readonly agentName: string;
+    constructor(agentName: string, cause: unknown);
+}
+export declare class RouterAgentLifecycleError extends RouterError {
+    readonly name = "RouterAgentLifecycleError";
+    readonly kind: "router_agent_lifecycle";
+    readonly agentName: string;
+    readonly operation: "start" | "stop" | "remove";
+    constructor(agentName: string, operation: "start" | "stop" | "remove", cause: unknown);
+}
+export declare class MultiAgentRouter {
+    #private;
+    constructor(opts: MultiAgentRouterOptions);
+    addAgent(config: RouterAgentConfig): void;
+    removeAgent(selector: RouterAgentSelector): Promise<void>;
+    getAgent(selector: RouterAgentSelector): RouterAgentRuntime;
+    listAgents(): readonly AgentInstanceSnapshot[];
+    snapshot(): RouterSnapshot;
+    startAgent(selector: RouterAgentSelector): Promise<AgentInstanceSnapshot>;
+    stopAgent(selector: RouterAgentSelector, reason?: string): Promise<void>;
+    startAll(): Promise<RouterSnapshot>;
+    stopAll(reason?: string): Promise<void>;
+    joinQueue(selector: RouterAgentSelector, game: string, mode?: string, opts?: {
+        readonly oneShot?: boolean;
+        readonly count?: number;
+    }): void;
+    leaveQueue(selector: RouterAgentSelector): void;
+    confirmMatch(selector: RouterAgentSelector, confirmId?: string): void;
+}

package/dist/types/daemon/runtime-files-write.d.ts

@@ -0,0 +1,76 @@
+export type RuntimeFilesWriteErrorKind = "write_failed" | "lock_held_by_other" | "lock_acquire_failed";
+export declare class RuntimeFilesWriteError extends Error {
+    readonly name = "RuntimeFilesWriteError";
+    readonly kind: RuntimeFilesWriteErrorKind;
+    readonly filePath: string;
+    /** Set when kind === "lock_held_by_other"; the holding process's PID
+     *  as recorded in the pid file. Caller maps to exit-6 + user message. */
+    readonly heldByPid?: number;
+    readonly cause?: unknown;
+    constructor(kind: RuntimeFilesWriteErrorKind, filePath: string, message: string, init?: {
+        heldByPid?: number;
+        cause?: unknown;
+    });
+}
+/** Generates a fresh 64-char hex token (32 random bytes encoded). */
+export declare function generateToken(): string;
+/** Atomic write: token file at `getRuntimeHome()/token` mode 0600.
+ *  Internal: writes to `<path>.<pid>.<counter>.tmp` then `fs.renameSync`.
+ *  Asserts token matches /^[0-9a-f]{64}$/ before write (TED Q2 — hex
+ *  literal assertion to defeat future regressions that swap the random
+ *  source for one emitting non-printable bytes / mixed case). */
+export declare function writeToken(token: string): void;
+/** Atomic write: port file at `getRuntimeHome()/port` mode 0644.
+ *  Content = `String(port)` no trailing newline. Range checked
+ *  [1, 65535] (matches M1-17 read-side validator). */
+export declare function writePort(port: number): void;
+/** Atomic write: pid file at `getRuntimeHome()/pid` mode 0644.
+ *  Content = `String(pid)` no trailing newline. */
+export declare function writePid(pid: number): void;
+/** Best-effort unlink of token + port + pid files on graceful shutdown.
+ *  ENOENT is silent (file already gone). Other failures only log via
+ *  onLog so shutdown sequence never throws on cleanup. */
+export declare function unlinkRuntimeFiles(opts: {
+    onLog?: (msg: string) => void;
+}): void;
+/** Cleans up `*.tmp` files in `getRuntimeHome()` left over from a
+ *  previous daemon crash. Called once at startup before any write.
+ *  Failures silent — best-effort only. */
+export declare function cleanupStaleTmpFiles(): void;
+export interface LockHandle {
+    /** Releases lock + unlinks lock file. Idempotent — second call no-op. */
+    release(): void;
+}
+export interface AcquireDaemonLockOptions {
+    /** Override `process.kill(pid, 0)` liveness probe for tests. Default
+     *  uses `process.kill(pid, 0)` and treats EPERM (cross-user, can't
+     *  signal) as `true` (alive) so we never overwrite a foreign daemon's
+     *  lock — TED 拍板点 #6 + Group 2 case 17 "EPERM 不能确认 → safe
+     *  保留". Production callers omit this option. */
+    readonly processIsAlive?: (pid: number) => boolean;
+}
+/** Acquire exclusive lock at `getRuntimeHome()/lock` (`O_EXCL` create).
+ *
+ *  Outcomes when the lock file already exists (EEXIST):
+ *  - **valid pid + alive (per probe)** → throw `lock_held_by_other`
+ *    with `heldByPid` set; lock + pid files preserved.
+ *  - **valid pid + dead** → STALE; clean lock + pid + retry once.
+ *  - **pid file missing / corrupt content / read error** → AMBIGUOUS;
+ *    throw `lock_acquire_failed`, **preserve lock + pid files**, do
+ *    not invoke the liveness probe. This window is exactly when a
+ *    racing daemon has just acquired the lock but has not yet written
+ *    its pid (Step 2 startup order: `acquireDaemonLock()` then
+ *    `writePid(process.pid)`); collapsing it into stale-cleanup would
+ *    let daemon B steal daemon A's live lock and acquire its own
+ *    (TED rev8 review-fix — multi-instance guarantee P1).
+ *  - **stale-cleanup retry STILL races (EEXIST again)** → throw
+ *    `lock_acquire_failed` (rare; another daemon snuck in between
+ *    our unlink and our second openSync).
+ *  - **non-EEXIST FS error on openSync** (permission denied, ENOSPC,
+ *    etc.) → throw `lock_acquire_failed`.
+ *  - **same process already holds this exact lock** → throw
+ *    `lock_acquire_failed` (reentrancy guard, TED Group 2 case 19).
+ *
+ *  Caller maps `lock_held_by_other` to exit 6 ("daemon already
+ *  running"); `lock_acquire_failed` to exit 1 (TED 拍板点 #8). */
+export declare function acquireDaemonLock(opts?: AcquireDaemonLockOptions): LockHandle;

package/dist/types/decision/direct-model/anthropic.d.ts

@@ -0,0 +1,12 @@
+import type { DirectModelClient } from "./types";
+export interface AnthropicClientOptions {
+    readonly apiKey: string;
+    readonly model: string;
+    /** Default "https://api.anthropic.com". Trailing slashes are stripped. */
+    readonly baseURL?: string;
+    /** Default "2023-06-01" (current Messages API). */
+    readonly anthropicVersion?: string;
+    /** Test injection point. Defaults to globalThis.fetch. */
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createAnthropicClient(opts: AnthropicClientOptions): DirectModelClient;

package/dist/types/decision/direct-model/errors.d.ts

@@ -0,0 +1,59 @@
+import type { DirectModelProviderName } from "./types";
+export type DirectModelErrorKind = "direct_model_network" | "direct_model_http" | "direct_model_aborted" | "direct_model_invalid_response" | "direct_model_unsupported";
+export declare abstract class DirectModelError extends Error {
+    abstract readonly kind: DirectModelErrorKind;
+    readonly provider: DirectModelProviderName;
+    readonly cause: unknown;
+    protected constructor(provider: DirectModelProviderName, message: string, cause?: unknown);
+}
+/** fetch() threw before producing a Response. Wraps the underlying
+ *  Node net / TLS / DNS error (or whatever fetch surfaced). */
+export declare class DirectModelNetworkError extends DirectModelError {
+    readonly name = "DirectModelNetworkError";
+    readonly kind: "direct_model_network";
+    constructor(provider: DirectModelProviderName, message: string, cause?: unknown);
+}
+/** HTTP response with non-2xx status. `bodySnippet` is the response
+ *  payload after redaction + truncation (≤ SNIPPET_MAX); callers
+ *  SHOULD NOT JSON.parse it without checking Content-Type. */
+export declare class DirectModelHttpError extends DirectModelError {
+    readonly name = "DirectModelHttpError";
+    readonly kind: "direct_model_http";
+    readonly status: number;
+    readonly bodySnippet?: string;
+    constructor(provider: DirectModelProviderName, status: number, message: string, bodySnippet?: string, cause?: unknown);
+}
+/** Caller-supplied AbortSignal fired (either pre-aborted or
+ *  mid-flight). Distinguished from DirectModelNetworkError so the
+ *  caller can suppress retry on intentional cancel. */
+export declare class DirectModelAbortedError extends DirectModelError {
+    readonly name = "DirectModelAbortedError";
+    readonly kind: "direct_model_aborted";
+    constructor(provider: DirectModelProviderName, message: string, cause?: unknown);
+}
+/** 2xx response but the body could not be parsed as JSON, or the
+ *  parsed shape did not match the expected provider envelope (e.g.
+ *  Anthropic missing `content[0].text`, OpenAI missing
+ *  `choices[0].message.content`). `responseSnippet` is redacted +
+ *  truncated. */
+export declare class DirectModelInvalidResponseError extends DirectModelError {
+    readonly name = "DirectModelInvalidResponseError";
+    readonly kind: "direct_model_invalid_response";
+    readonly responseSnippet?: string;
+    constructor(provider: DirectModelProviderName, message: string, responseSnippet?: string, cause?: unknown);
+}
+/** Caller passed an option that fails synchronous validation
+ *  (empty apiKey, empty model, maxTokens <= 0, etc). Thrown before
+ *  any network call. `field` names the offending option for
+ *  programmatic handling (don't parse message text). */
+export declare class DirectModelUnsupportedError extends DirectModelError {
+    readonly name = "DirectModelUnsupportedError";
+    readonly kind: "direct_model_unsupported";
+    readonly field: string;
+    constructor(provider: DirectModelProviderName, field: string, message: string);
+}
+export declare const SNIPPET_MAX = 2048;
+export declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+export declare function redactSecrets(s: string, secrets: readonly string[]): string;
+export declare function truncateSnippet(s: string, max?: number): string;
+export declare function sanitizeSnippet(raw: string | undefined, secrets: readonly string[]): string | undefined;

package/dist/types/decision/direct-model/openai.d.ts

@@ -0,0 +1,12 @@
+import type { DirectModelClient } from "./types";
+export interface OpenAIClientOptions {
+    readonly apiKey: string;
+    readonly model: string;
+    /** Default "https://api.openai.com/v1". Trailing slashes stripped. */
+    readonly baseURL?: string;
+    /** Optional OpenAI-Organization header. */
+    readonly organization?: string;
+    /** Test injection point. Defaults to globalThis.fetch. */
+    readonly fetchImpl?: typeof fetch;
+}
+export declare function createOpenAIClient(opts: OpenAIClientOptions): DirectModelClient;

package/dist/types/decision/direct-model/types.d.ts

@@ -0,0 +1,20 @@
+export type DirectModelProviderName = "anthropic" | "openai";
+export interface DirectModelGenerateRequest {
+    readonly systemPrompt: string;
+    readonly userPrompt: string;
+    readonly temperature?: number;
+    readonly maxTokens: number;
+    readonly signal?: AbortSignal;
+}
+export interface DirectModelGenerateResponse {
+    readonly text: string;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly latencyMs: number;
+    readonly raw: unknown;
+}
+export interface DirectModelClient {
+    readonly provider: DirectModelProviderName;
+    readonly model: string;
+    generate(req: DirectModelGenerateRequest): Promise<DirectModelGenerateResponse>;
+}

package/dist/types/decision/parser-types.d.ts

@@ -0,0 +1,31 @@
+import type { LegalAction } from "./types";
+export type ParseInvalidReason = "json_parse" | "missing_fields" | "unknown_action_type" | "action_not_legal" | "data_validation";
+export type ParseResult = {
+    readonly kind: "ok";
+    /**
+     * For simple / server-enumerated actions, this is the original
+     * server-provided `LegalAction` reference (reference equality
+     * holds against the matching entry in `legalActions`). For
+     * Texas Hold'em `raise` and Liar's Dice `bid`, the LLM picks
+     * the concrete amount / quantity-face within the server hints,
+     * so the parser constructs a fresh `{ type, data }` object —
+     * reference equality with `legalActions[i]` does NOT hold for
+     * those two cases (M1-14 拍板点 #5 + Risks #10).
+     */
+    readonly action: LegalAction;
+    /**
+     * Optional one-line reasoning extracted from the LLM JSON
+     * (`{"summary": ...}`). M1-14 provider passes this through to
+     * `DecisionResponse.summary` without re-parsing.
+     */
+    readonly summary?: string;
+} | {
+    readonly kind: "invalid";
+    readonly reason: ParseInvalidReason;
+    /**
+     * Up to `parseRetryHintCharCap` chars (default 500) of the raw
+     * LLM output, used to populate the corrective re-prompt. Parser
+     * is responsible for truncation; provider does not re-truncate.
+     */
+    readonly rawSnippet?: string;
+};

package/dist/types/decision/prompt-builder.d.ts

@@ -0,0 +1,10 @@
+import type { DecisionRequest } from "./types";
+export interface PromptBuilderOptions {
+    /** Hard cap on assembled userPrompt length (chars). Default 16384. */
+    readonly userPromptCharCap?: number;
+}
+export interface BuiltPrompt {
+    readonly systemPrompt: string;
+    readonly userPrompt: string;
+}
+export declare function buildPrompt(req: DecisionRequest, options?: PromptBuilderOptions): BuiltPrompt;

package/dist/types/decision/provider.d.ts

@@ -0,0 +1,50 @@
+import { createAnthropicClient } from "./direct-model/anthropic";
+import { createOpenAIClient } from "./direct-model/openai";
+import type { DirectModelProviderName } from "./direct-model/types";
+import type { DecisionRequest, DecisionResponse } from "./types";
+export type { DirectModelProviderName } from "./direct-model/types";
+export interface DecisionProvider {
+    readonly name: string;
+    decide(req: DecisionRequest): Promise<DecisionResponse>;
+    healthCheck(): Promise<boolean>;
+}
+export interface DirectModelProviderOptions {
+    /** Identifier for this provider instance. plan §5.5
+     *  DecisionProvider.name. */
+    readonly name: string;
+    /** Returns API key for the given (provider, model). Caller decides
+     *  the source (env / keychain / file per plan §5.7 layer 2). Must be
+     *  synchronous so the factory itself stays sync. Returning an empty
+     *  string causes `decide()` to throw a fatal_unsupported error and
+     *  `healthCheck()` to return false. */
+    readonly apiKeyResolver: (provider: DirectModelProviderName, model: string) => string;
+    /** Override for the direct-model client factories (testing). When
+     *  omitted, defaults to the M1-11 `createAnthropicClient` /
+     *  `createOpenAIClient`. */
+    readonly clientFactory?: {
+        readonly anthropic?: typeof createAnthropicClient;
+        readonly openai?: typeof createOpenAIClient;
+    };
+    /** Default 2. Total LLM calls = 1 + retryBudget. */
+    readonly retryBudget?: number;
+    /** Default 500. Max chars of raw LLM output threaded into the
+     *  corrective re-prompt. */
+    readonly parseRetryHintCharCap?: number;
+    /** Override for transport. Passed through to the client factory. */
+    readonly fetchImpl?: typeof fetch;
+    /** Explicit healthCheck target. When omitted, `healthCheck()`
+     *  returns false (catch-all consistent with the
+     *  `Promise<boolean>` contract). M1-14 rev3 锁:无 profile → false。 */
+    readonly healthCheckProfile?: {
+        readonly provider: DirectModelProviderName;
+        readonly model: string;
+    };
+}
+export type DecisionProviderErrorKind = "fatal_http" | "fatal_aborted" | "fatal_unsupported" | "fatal_caller_bug";
+export declare class DecisionProviderError extends Error {
+    readonly name = "DecisionProviderError";
+    readonly kind: DecisionProviderErrorKind;
+    readonly cause: unknown;
+    constructor(kind: DecisionProviderErrorKind, message: string, cause?: unknown);
+}
+export declare function createDirectModelProvider(opts: DirectModelProviderOptions): DecisionProvider;

package/dist/types/decision/types.d.ts

@@ -0,0 +1,87 @@
+import type { Action, CoupRules, Event, LiarsDiceRules, PlayerInfo, TexasHoldemRules } from "../protocol/types";
+export type GameType = "texas_holdem" | "liars_dice" | "coup";
+export type GameRules = {
+    readonly game: "texas_holdem";
+    readonly rules: TexasHoldemRules;
+} | {
+    readonly game: "liars_dice";
+    readonly rules: LiarsDiceRules;
+} | {
+    readonly game: "coup";
+    readonly rules: CoupRules;
+};
+export type LegalAction = Action;
+export interface GameSpecificProfile {
+    readonly extraPrompt?: string;
+    /**
+     * [0..1] risk-aversion hyperparameter. Information-only for M1-12;
+     * consumed by M1-14 (rev3 锁:M1-13 fallback 也不读).
+     */
+    readonly riskAversion?: number;
+}
+export interface StrategyProfile {
+    readonly name: string;
+    readonly version: number;
+    readonly provider: "anthropic" | "openai";
+    readonly model: string;
+    readonly systemPrompt: string;
+    readonly temperature?: number;
+    readonly maxTokens: number;
+    readonly costCapUSDPerMatch?: number;
+    readonly gameSpecific?: Partial<Record<GameType, GameSpecificProfile>>;
+}
+export interface DecisionRequest {
+    readonly game: GameType;
+    readonly matchId: string;
+    readonly playerId: string;
+    /**
+     * Game-specific rules from server_game_start.data.rules. Caller
+     * must ensure shape matches the `game` discriminator
+     * (TexasHoldemRules / LiarsDiceRules / CoupRules per
+     * protocol/types.ts MsgGameStartDataTexasHoldem / LiarsDice / Coup).
+     */
+    readonly rules: GameRules["rules"];
+    readonly legalActions: readonly LegalAction[];
+    /**
+     * Game-specific state from action_request.data.state. Protocol-
+     * level shape is opaque (`state: {}` per messages/server_action_
+     * request.schema.json); narrowing is per-game. M1-12 prompt-
+     * builder dispatches on `game` and treats this as the per-game
+     * state shape (TexasHoldemState / LiarsDiceState / CoupState).
+     */
+    readonly publicState: unknown;
+    /**
+     * Reserved for future private-narrowed fields. Server currently
+     * embeds your_hand / your_dice / your_cards / coins inside
+     * publicState; this slot stays optional unknown for forward
+     * compatibility (M1-12 Risks #4).
+     */
+    readonly privateState?: unknown;
+    readonly players: readonly PlayerInfo[];
+    /**
+     * Incremental events since the player's last action_request
+     * (action_request.data.new_events). Caller MUST normalize null →
+     * [] before constructing DecisionRequest (M1-12 Risks #11; protocol
+     * spec allows `new_events: null` on first action_request).
+     */
+    readonly recentEvents: readonly Event[];
+    readonly strategyProfile: StrategyProfile;
+    readonly turnTimeoutMs: number;
+    readonly decisionBudgetMs: number;
+}
+export interface DecisionResponseProviderMetadata {
+    readonly provider: string;
+    readonly model: string;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly costUSD?: number;
+    readonly latencyMs: number;
+    readonly retries?: number;
+    readonly fallback?: boolean;
+}
+export interface DecisionResponse {
+    readonly action: string;
+    readonly params?: Record<string, unknown>;
+    readonly summary?: string;
+    readonly providerMetadata: DecisionResponseProviderMetadata;
+}

package/dist/types/games/_shared/player-info.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read `data[key]` as a finite number. Returns `undefined` if `data` is
+ * not a non-null object, the field is missing, the value is not a
+ * number, or the value is NaN / Infinity / -Infinity. Caller must omit
+ * the output field on `undefined` (never default to 0).
+ */
+export declare function readNumberField(data: unknown, key: string): number | undefined;
+/**
+ * Read `data[key]` as `string[]`. Returns `undefined` if `data` is not a
+ * non-null object, the field is missing, the value is not an array, or
+ * any element is not a string. Returns the array reference (no copy) —
+ * read-only by convention; caller must NOT mutate.
+ */
+export declare function readStringArrayField(data: unknown, key: string): string[] | undefined;

package/dist/types/games/coup/action-parser.d.ts

@@ -0,0 +1,3 @@
+import type { LegalAction } from "../../decision/types";
+import type { ParseResult } from "../../decision/parser-types";
+export declare function parseCoupAction(rawText: string, legalActions: readonly LegalAction[], rawSnippetCap?: number): ParseResult;

package/dist/types/games/coup/fallback.d.ts

@@ -0,0 +1,8 @@
+import type { LegalAction } from "../../decision/types";
+import type { CoupState } from "../../protocol/types";
+export interface CoupFallbackInput {
+    readonly publicState: CoupState;
+    readonly legalActions: readonly LegalAction[];
+    readonly yourPlayerId: string;
+}
+export declare function fallbackCoup(input: CoupFallbackInput): LegalAction;

package/dist/types/games/coup/state-formatter.d.ts

@@ -0,0 +1,14 @@
+import type { CoupRules, CoupState, Event, PlayerInfo } from "../../protocol/types";
+export interface CoupFormatterInput {
+    readonly publicState: CoupState;
+    readonly privateState?: unknown;
+    readonly rules: CoupRules;
+    readonly players: readonly PlayerInfo[];
+    readonly recentEvents: readonly Event[];
+    readonly yourPlayerId: string;
+}
+export interface StateFormatterOutput {
+    readonly stateBlock: string;
+    readonly recentEventsBlock: string;
+}
+export declare function formatCoupState(input: CoupFormatterInput): StateFormatterOutput;

package/dist/types/games/liars_dice/action-parser.d.ts

@@ -0,0 +1,3 @@
+import type { LegalAction } from "../../decision/types";
+import type { ParseResult } from "../../decision/parser-types";
+export declare function parseLiarsDiceAction(rawText: string, legalActions: readonly LegalAction[], rawSnippetCap?: number): ParseResult;

package/dist/types/games/liars_dice/fallback.d.ts

@@ -0,0 +1,8 @@
+import type { LegalAction } from "../../decision/types";
+import type { LiarsDiceState } from "../../protocol/types";
+export interface LiarsDiceFallbackInput {
+    readonly publicState: LiarsDiceState;
+    readonly legalActions: readonly LegalAction[];
+    readonly yourPlayerId: string;
+}
+export declare function fallbackLiarsDice(input: LiarsDiceFallbackInput): LegalAction;

package/dist/types/games/liars_dice/state-formatter.d.ts

@@ -0,0 +1,14 @@
+import type { Event, LiarsDiceRules, LiarsDiceState, PlayerInfo } from "../../protocol/types";
+export interface LiarsDiceFormatterInput {
+    readonly publicState: LiarsDiceState;
+    readonly privateState?: unknown;
+    readonly rules: LiarsDiceRules;
+    readonly players: readonly PlayerInfo[];
+    readonly recentEvents: readonly Event[];
+    readonly yourPlayerId: string;
+}
+export interface StateFormatterOutput {
+    readonly stateBlock: string;
+    readonly recentEventsBlock: string;
+}
+export declare function formatLiarsDiceState(input: LiarsDiceFormatterInput): StateFormatterOutput;

package/dist/types/games/texas_holdem/action-parser.d.ts

@@ -0,0 +1,3 @@
+import type { LegalAction } from "../../decision/types";
+import type { ParseResult } from "../../decision/parser-types";
+export declare function parseTexasHoldemAction(rawText: string, legalActions: readonly LegalAction[], rawSnippetCap?: number): ParseResult;

package/dist/types/games/texas_holdem/fallback.d.ts

@@ -0,0 +1,8 @@
+import type { LegalAction } from "../../decision/types";
+import type { TexasHoldemState } from "../../protocol/types";
+export interface TexasHoldemFallbackInput {
+    readonly publicState: TexasHoldemState;
+    readonly legalActions: readonly LegalAction[];
+    readonly yourPlayerId: string;
+}
+export declare function fallbackTexasHoldem(input: TexasHoldemFallbackInput): LegalAction;

package/dist/types/games/texas_holdem/state-formatter.d.ts

@@ -0,0 +1,14 @@
+import type { Event, PlayerInfo, TexasHoldemRules, TexasHoldemState } from "../../protocol/types";
+export interface TexasHoldemFormatterInput {
+    readonly publicState: TexasHoldemState;
+    readonly privateState?: unknown;
+    readonly rules: TexasHoldemRules;
+    readonly players: readonly PlayerInfo[];
+    readonly recentEvents: readonly Event[];
+    readonly yourPlayerId: string;
+}
+export interface StateFormatterOutput {
+    readonly stateBlock: string;
+    readonly recentEventsBlock: string;
+}
+export declare function formatTexasHoldemState(input: TexasHoldemFormatterInput): StateFormatterOutput;