@aifight/aifight 0.1.0-alpha.1

package/dist/types/cli/commands/service/types.d.ts

@@ -0,0 +1,64 @@
+/** Service platform identifier — combines OS + service manager.
+ *  - "linux-systemd-user": Linux with `systemctl --user` reachable.
+ *  - "darwin-launchd-user": macOS with `launchctl` reachable.
+ *  - "unsupported": Windows native, Linux without systemd `--user`,
+ *    macOS without launchctl, or any other POSIX. */
+export type ServicePlatform = "linux-systemd-user" | "darwin-launchd-user" | "unsupported";
+/** install() options. Passed from `runServiceInstall` handler to the
+ *  selected `ServiceTarget` (systemd or launchd).
+ *
+ *  rev4 contract:
+ *    - `autoStart=false` (--no-start) on linux: skip `systemctl start` after enable.
+ *    - `autoStart=false` (--no-start) on launchd: plist writes RunAtLoad=false,
+ *      still runs `launchctl bootstrap` (registers LaunchAgent) but skips kickstart.
+ *    - `printOnly=true` (--print): generator emits unit/plist text to stdout,
+ *      writes nothing, runs no systemctl/launchctl. exit 0.
+ *    - `envFile` is systemd-only; darwin handlers exit 2 with
+ *      `client_env_file_unsupported_on_darwin` BEFORE createLaunchdTarget. */
+export interface ServiceInstallOptions {
+    readonly autoStart: boolean;
+    readonly printOnly: boolean;
+    readonly envFile?: string;
+}
+/** uninstall() options. */
+export interface ServiceUninstallOptions {
+    /** When true, also `rm -rf $AIFIGHT_RUNTIME_HOME` after stop+disable+removing
+     *  unit/plist (拍板点 #8). Plain `--purge` flag is the user's destructive
+     *  opt-in; handler prints a warning line in human mode but does NOT prompt. */
+    readonly purge: boolean;
+}
+/** status() result — three-state contract (拍板点 #6). */
+export type ServiceStatus = {
+    kind: "not_installed";
+} | {
+    kind: "stopped";
+    /** Optional sub-status from the underlying service manager:
+     *  - systemd: `is-active` raw output (`inactive` / `failed` / `activating` / ...)
+     *  - launchd: parsed state (`waiting` / `unknown` / ...) */
+    substatus?: string;
+} | {
+    kind: "running";
+    /** systemd: parsed `MainPID`; launchd: parsed `pid`.
+     *  Best-effort; absent when parser fails (Open Question #6). */
+    pid?: number;
+    /** systemd: parsed `ActiveEnterTimestamp`; launchd: not always available.
+     *  ISO 8601 string when present. */
+    since?: string;
+};
+/** Common shape for systemd + launchd targets. The handlers in
+ *  `service-install.ts` consume this interface; both target factories
+ *  (`createSystemdTarget` + `createLaunchdTarget`) return implementations. */
+export interface ServiceTarget {
+    /** Absolute path of the generated unit/plist:
+     *  - systemd: `~/.config/systemd/user/aifight.service`
+     *  - launchd: `~/Library/LaunchAgents/ai.aifight.runtime.plist` */
+    readonly unitPath: string;
+    /** Pure — produces the unit/plist text. Used for `--print` dry-run +
+     *  snapshot tests + diff detection on existing files. */
+    generate(): string;
+    install(opts: ServiceInstallOptions): Promise<void>;
+    uninstall(opts: ServiceUninstallOptions): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    status(): Promise<ServiceStatus>;
+}

package/dist/types/cli/commands/service-install.d.ts

@@ -0,0 +1,29 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+import { type OsPlatform, type ServiceExecFile } from "./service/platform";
+export type ServiceErrorCode = "client_unsupported_flag" | "client_platform_unsupported" | "client_service_manager_missing" | "client_env_file_missing" | "client_env_file_unsupported_on_darwin" | "client_already_installed_diff" | "client_not_installed" | "client_aifight_exec_unresolved" | "client_install_failed" | "client_uninstall_failed" | "client_start_failed" | "client_stop_failed";
+export declare function emitServiceError(env: HandlerEnv, jsonMode: boolean, exitCode: number, code: ServiceErrorCode, humanMessage: string, hint?: string): number;
+export declare function resolveAifightExec(candidate: string | undefined, execFile: ServiceExecFile): Promise<string>;
+export interface ServiceDeps {
+    /** ExecFile injection for tests. Defaults to `defaultExecFile`. */
+    readonly execFile?: ServiceExecFile;
+    /** Pre-resolved aifight binary path. When provided, the install
+     *  handler skips `resolveAifightExec(process.argv[1], ...)` —
+     *  necessary in tests because `process.argv[1]` typically points at
+     *  the vitest worker, not a real aifight binary. */
+    readonly aifightExec?: string;
+    /** OS platform override for tests. Defaults to `detectOsPlatform()`. */
+    readonly osPlatform?: OsPlatform;
+    /** Effective UID for `gui/$UID` selector on darwin. Defaults to
+     *  `process.getuid?.() ?? 0`. */
+    readonly uid?: number;
+    /** Path overrides — production picks under `~`. Tests inject tmp dirs. */
+    readonly systemdUnitPath?: string;
+    readonly launchdPlistPath?: string;
+    readonly launchdLogDir?: string;
+    readonly runtimeHome?: string;
+}
+export declare function runServiceInstall(args: HandlerArgs, env: HandlerEnv, deps?: ServiceDeps): Promise<number>;
+export declare function runServiceUninstall(args: HandlerArgs, env: HandlerEnv, deps?: ServiceDeps): Promise<number>;
+export declare function runServiceStart(args: HandlerArgs, env: HandlerEnv, deps?: ServiceDeps): Promise<number>;
+export declare function runServiceStop(args: HandlerArgs, env: HandlerEnv, deps?: ServiceDeps): Promise<number>;
+export declare function runServiceStatus(args: HandlerArgs, env: HandlerEnv, deps?: ServiceDeps): Promise<number>;

package/dist/types/cli/commands/setup.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runSetup(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/shutdown.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runShutdown(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/commands/stubs.d.ts

@@ -0,0 +1,24 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+interface PureStubOptions {
+    /** User-visible canonical name, e.g. "setup" / "service install" / "results". */
+    readonly command: string;
+    readonly arityMin: number;
+    readonly arityMax: number;
+    readonly usage: string;
+    /** Tier B carries milestone (e.g. "M1-18 daemon lifecycle"); Tier C omits. */
+    readonly milestone?: string;
+}
+/** Factory that returns a Tier B / Tier C stub handler. */
+export declare function pureStub(opts: PureStubOptions): (args: HandlerArgs, env: HandlerEnv) => Promise<number>;
+export declare function tierBStub(command: string, milestone: string, arity?: {
+    readonly min: number;
+    readonly max: number;
+}, usage?: string): (args: HandlerArgs, env: HandlerEnv) => Promise<number>;
+export declare function tierCStub(command: string, arity?: {
+    readonly min: number;
+    readonly max: number;
+}, usage?: string): (args: HandlerArgs, env: HandlerEnv) => Promise<number>;
+export declare function runAgentAdd(args: HandlerArgs, env: HandlerEnv): Promise<number>;
+export declare function runAgentRemove(args: HandlerArgs, env: HandlerEnv): Promise<number>;
+export declare function doctorFixSkillOverrideStub(): (args: HandlerArgs, env: HandlerEnv) => Promise<number>;
+export {};

package/dist/types/cli/commands/version.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerArgs, HandlerEnv } from "../shared";
+export declare function runVersion(args: HandlerArgs, env: HandlerEnv): Promise<number>;

package/dist/types/cli/control-client.d.ts

@@ -0,0 +1,59 @@
+export type ControlErrorCodeLocal = "unauthorized" | "not_found" | "method_not_allowed" | "bad_request" | "unsupported_media_type" | "payload_too_large" | "not_implemented" | "service_unavailable" | "internal_error";
+export declare function isControlErrorCode(x: unknown): x is ControlErrorCodeLocal;
+export interface ControlErrorBodyLocal {
+    readonly error: {
+        readonly code: ControlErrorCodeLocal;
+        readonly message: string;
+        readonly details?: Readonly<Record<string, unknown>>;
+    };
+}
+export declare function isControlErrorBody(x: unknown): x is ControlErrorBodyLocal;
+export type ControlClientErrorKind = "daemon_unreachable" | "runtime_files_corrupt" | "auth_failed" | "request_timeout" | "server_error" | "transport_unparseable";
+export interface ControlClientErrorInit {
+    readonly serverCode?: ControlErrorCodeLocal;
+    readonly status?: number;
+    readonly body?: unknown;
+    readonly cause?: unknown;
+}
+export declare class ControlClientError extends Error {
+    readonly name = "ControlClientError";
+    readonly kind: ControlClientErrorKind;
+    readonly serverCode?: ControlErrorCodeLocal;
+    readonly status: number;
+    readonly body?: unknown;
+    readonly cause?: unknown;
+    constructor(kind: ControlClientErrorKind, message: string, init?: ControlClientErrorInit);
+}
+export interface ControlClient {
+    /** GET <path>. Returns parsed JSON body. 4xx/5xx → throw ControlClientError. */
+    get<T = unknown>(path: string): Promise<T>;
+    /** POST <path> with body.
+     *  - body === undefined → no Content-Type / no payload (use this for
+     *    /shutdown, /pause, /resume, /leave).
+     *  - body === null → Content-Type: application/json + literal "null".
+     *  - object → Content-Type: application/json + JSON.stringify. */
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** DELETE <path>. */
+    delete<T = unknown>(path: string): Promise<T>;
+}
+export interface CreateControlClientOptions {
+    /** Sync, lazy — invoked at the moment of each request, NOT at client
+     *  construction. Construction MUST succeed even if the source would
+     *  throw, so bridge-independent commands (version / --help / doctor)
+     *  can construct a client without a running Bridge. */
+    readonly tokenSource: () => string;
+    /** Same lazy semantics + same wrap-at-boundary contract as tokenSource. */
+    readonly portSource: () => number;
+    /** Default "127.0.0.1". */
+    readonly host?: string;
+    /** Per-request timeout. Default 10000 ms. */
+    readonly baseTimeoutMs?: number;
+    /** Injectable for tests. Default globalThis.fetch. */
+    readonly fetchImpl?: typeof fetch;
+    /** Optional log hook (rebootstrap reason etc.). MUST NOT receive token. */
+    readonly onLog?: (event: {
+        code: string;
+        message: string;
+    }) => void;
+}
+export declare function createControlClient(opts: CreateControlClientOptions): ControlClient;

package/dist/types/cli/format.d.ts

@@ -0,0 +1,52 @@
+/** Minimal duck-type of M1-16 SanitizedAgentSnapshot we render. */
+interface AgentSnapshotLike {
+    readonly name: string;
+    readonly started: boolean;
+    readonly stopped: boolean;
+    readonly transport?: string;
+    readonly state: AgentStateLike | null;
+}
+interface AgentStateLike {
+    readonly phase?: string;
+    readonly agentId?: string;
+    readonly agentName?: string;
+    readonly availableGames?: readonly string[];
+    readonly autoConfirmMatches?: boolean;
+    readonly queue?: {
+        readonly game: string;
+        readonly mode: string;
+    };
+    readonly activeMatch?: {
+        readonly sessionId: string;
+        readonly game: string;
+        readonly startedAt: number;
+    };
+}
+interface DailyScheduleConfigLike {
+    readonly enabled: boolean;
+    readonly timezone: string;
+    readonly minIntervalSec?: number;
+    readonly days: Readonly<Record<string, {
+        readonly count: number;
+    }>>;
+}
+export declare function formatAgentTable(agents: readonly AgentSnapshotLike[]): string;
+export declare function formatAgentStatus(agent: AgentSnapshotLike): string;
+interface ScheduleSnapshotLike {
+    readonly running: boolean;
+    /** YYYY-MM-DD local date (M1-15 DailySchedulerSnapshot.today) or null
+     *  when scheduler has not yet computed the boundary. */
+    readonly today?: string | null;
+    readonly remaining?: Readonly<Record<string, number>>;
+    readonly nextFireInMs?: number | null;
+    readonly lastAttempt?: {
+        readonly outcome?: string;
+        readonly game?: string | null;
+        readonly atMs?: number;
+    } | null;
+}
+export declare function formatScheduleShow(cfg: DailyScheduleConfigLike | null, snap: ScheduleSnapshotLike): string;
+/** Compose a JSON-mode error envelope. Used by main.ts error funnel and
+ *  by handlers that surface a usage error in JSON mode. */
+export declare function jsonErrorEnvelope(code: string, message: string, details?: Readonly<Record<string, unknown>>): string;
+export {};

package/dist/types/cli/main.d.ts

@@ -0,0 +1,18 @@
+import type { HelloResult } from "../index";
+import type { BridgeServiceDeps } from "../bridge/service";
+export interface RunOptions {
+    readonly stdout?: (s: string) => void;
+    readonly stderr?: (s: string) => void;
+    /** Override for M1-01 hello() (used by doctor schemas check). */
+    readonly hello?: () => HelloResult;
+    /** Override fetch (used by tests). */
+    readonly fetchImpl?: typeof fetch;
+    /** Reserved for injected command handlers that need a shorter network timeout. */
+    readonly baseTimeoutMs?: number;
+    readonly onLog?: (event: {
+        code: string;
+        message: string;
+    }) => void;
+    readonly bridgeService?: BridgeServiceDeps;
+}
+export declare function run(argv: readonly string[], opts?: RunOptions): Promise<number>;

package/dist/types/cli/runtime-files.d.ts

@@ -0,0 +1,11 @@
+export type RuntimeFilesErrorKind = "token_missing" | "port_missing" | "token_corrupt" | "port_corrupt";
+export declare class RuntimeFilesError extends Error {
+    readonly name = "RuntimeFilesError";
+    readonly kind: RuntimeFilesErrorKind;
+    readonly filePath: string;
+    constructor(kind: RuntimeFilesErrorKind, filePath: string, message: string);
+}
+export declare function tokenFilePath(): string;
+export declare function portFilePath(): string;
+export declare function readToken(): string;
+export declare function readPort(): number;

package/dist/types/cli/shared.d.ts

@@ -0,0 +1,74 @@
+import type { ControlClient, CreateControlClientOptions } from "./control-client";
+import type { HelloResult } from "../index";
+import type { BridgeServiceDeps } from "../bridge/service";
+/** Per-handler injectable environment. Defaults wired to process I/O +
+ *  real fs + native fetch. Tests pass overrides for stdout/stderr capture
+ *  + hello stub + fetchImpl pointing at a temporary M1-16 server. */
+export interface HandlerEnv {
+    readonly stdout: (s: string) => void;
+    readonly stderr: (s: string) => void;
+    /** Override for the M1-01 schemas/types self-test used by `doctor`.
+     *  Default: real `hello` from runtime/src/index.ts (lazy-imported by
+     *  the doctor handler so other commands do not pull in the
+     *  schemas-loading cost). */
+    readonly hello?: () => HelloResult;
+    /** Override fetch implementation for tests. Default globalThis.fetch. */
+    readonly fetchImpl?: typeof fetch;
+    /** Optional rebootstrap log hook (forwarded to control-client). */
+    readonly onLog?: (event: {
+        code: string;
+        message: string;
+    }) => void;
+    /** Default 10000 ms per Step 2b directive (must not drop below ~3000
+     *  for normal commands). doctor uses its own 3000 ms one-shot fetch. */
+    readonly baseTimeoutMs?: number;
+    /** Optional bridge service manager overrides for tests and controlled installs. */
+    readonly bridgeService?: BridgeServiceDeps;
+}
+export interface HandlerArgs {
+    /** Positional argv with the command (and subcommand for `agent`/`daily`)
+     *  already stripped by the dispatcher in main.ts. */
+    readonly positional: readonly string[];
+    /** All globally-known flags merged from the single argv pass. */
+    readonly flags: Readonly<Record<string, string | number | boolean>>;
+    /** True when `--json` was set (any position — floating flag, rev2 fix #1). */
+    readonly jsonMode: boolean;
+}
+/** Build a controlClient that lazily reads token+port from the daemon
+ *  files. version / doctor / Tier B/C stubs do NOT call this. */
+export declare function makeClient(env: HandlerEnv, extra?: Partial<CreateControlClientOptions>): ControlClient;
+/** Centralised game enum for client-side validation (Risks #11 — CLI
+ *  hard-codes the supported list rather than fetching from server, so a
+ *  contract drift surfaces as a usage error rather than a daemon round
+ *  trip). */
+export declare const SUPPORTED_GAMES: ReadonlyArray<string>;
+export declare function isSupportedGame(g: string): boolean;
+/** Class for argv-parser-style usage errors that should map to exit 2.
+ *  Distinct from AgentResolverError (which uses its own kind discriminator). */
+export declare class UsageError extends Error {
+    readonly name = "UsageError";
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+/** Expected runtime/API failures that should be shown as ordinary command
+ * errors (exit 1), not catchall programmer failures (exit 99). */
+export declare class CommandError extends Error {
+    readonly name = "CommandError";
+    readonly code: string;
+    readonly exitCode: number;
+    readonly hint?: string;
+    constructor(code: string, message: string, opts?: {
+        readonly exitCode?: number;
+        readonly hint?: string;
+    });
+}
+/** Step 3b — assert positional arity at the top of every handler BEFORE
+ *  any side-effect (controlClient / network / fs). Extra positionals
+ *  must NOT silently fall through to a successful POST (e.g.
+ *  `aifight shutdown anything` previously still POSTed /v1/shutdown).
+ *
+ *  Throws UsageError → main.ts funnel maps to exit 2 + usage hint.
+ *  No-args handlers call `expectArity(args, 0, 0, "...")`;
+ *  optional-arg handlers (e.g. agent status [<name>]) use min=0 max=1;
+ *  fixed-arity handlers (e.g. daily set <game> <count>) use min=max=N. */
+export declare function expectArity(args: HandlerArgs, min: number, max: number, usage: string): void;

package/dist/types/controlapi/profile-routes.d.ts

@@ -0,0 +1,49 @@
+export interface ProfileRouteDeps {
+    /**
+     * Resolve the on-disk directory for an agent slug.
+     * Defaults to resolveAgentDir from profile-loader.
+     */
+    resolveAgentDir?: (slug: string) => string;
+    /**
+     * List session IDs for an agent from the daemon's active state.
+     * Returns [] when the daemon has no state for this slug or the function
+     * is not wired (stubs for CLI-only deployments).
+     */
+    listSessions?: (agentSlug: string) => SessionSummary[];
+    /**
+     * Fetch a single session summary by sessionId.
+     * Returns null when the session is not found.
+     */
+    getSessionSummary?: (sessionId: string) => SessionSummary | null;
+}
+export interface SessionSummary {
+    readonly sessionId: string;
+    readonly agentSlug: string;
+    readonly game: string;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly outcome?: "win" | "loss" | "draw" | "forfeit" | string;
+    readonly ratingDelta?: number;
+}
+export interface ProfileHandlerContext {
+    readonly params: Readonly<Record<string, string>>;
+    readonly body: unknown;
+}
+export interface ProfileRouteResult {
+    readonly status: number;
+    readonly body: unknown;
+}
+declare class ProfileRouteError extends Error {
+    readonly name = "ProfileRouteError";
+    readonly status: number;
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
+}
+export interface ProfileRoute {
+    readonly method: "GET" | "POST";
+    readonly path: string;
+    readonly handle: (ctx: ProfileHandlerContext) => Promise<ProfileRouteResult>;
+}
+export declare function createProfileRoutes(deps?: ProfileRouteDeps): ProfileRoute[];
+export { ProfileRouteError };

package/dist/types/controlapi/server.d.ts

@@ -0,0 +1,3 @@
+import type { ControlAgentHandle, ControlRouterTarget, ControlServer, ControlServerOptions } from "./types";
+export declare function createControlServer(opts: ControlServerOptions): ControlServer;
+export type { ControlAgentHandle, ControlRouterTarget };

package/dist/types/controlapi/types.d.ts

@@ -0,0 +1,136 @@
+import type { AgentInstanceSnapshot } from "../agents/agent";
+import type { DailyScheduler } from "../scheduler/daily";
+import type { DailyScheduleConfig } from "../scheduler/types";
+export interface ControlAgentHandle {
+    snapshot(): AgentInstanceSnapshot;
+}
+export interface ControlJoinQueueOptions {
+    readonly oneShot?: boolean;
+    readonly count?: number;
+}
+export interface ControlRouterTarget {
+    listAgents(): readonly AgentInstanceSnapshot[];
+    /** Throws RouterAgentNotFoundError when no agent matches. Handler
+     *  catches by `error.kind === "router_agent_not_found"` (duck-typed,
+     *  no instanceof) and maps to HTTP 404. Other RouterError kinds map
+     *  to 500 internal_error. */
+    getAgent(selector: {
+        readonly name: string;
+    }): ControlAgentHandle;
+    joinQueue(selector: {
+        readonly name: string;
+    }, game: string, mode?: string, opts?: ControlJoinQueueOptions): void;
+    leaveQueue(selector: {
+        readonly name: string;
+    }): void;
+}
+export type ControlLogLevel = "info" | "warn" | "error";
+export type ControlLogCode = "server_listening" | "server_closed" | "request_received" | "request_completed" | "auth_failed" | "handler_threw" | "shutdown_requested";
+export interface ControlLogEvent {
+    readonly level: ControlLogLevel;
+    readonly code: ControlLogCode;
+    readonly message: string;
+    readonly method?: string;
+    readonly path?: string;
+    readonly status?: number;
+    readonly durationMs?: number;
+    readonly host?: string;
+    readonly port?: number;
+    /** auth_failed: missing_header | invalid_format | token_mismatch | token_unset */
+    readonly reason?: string;
+    readonly cause?: unknown;
+}
+export interface ControlServerOptions {
+    /** Default "127.0.0.1". server binds 127.0.0.1 only — no remote
+     *  exposure path in M1; TLS / remote access is M5+ scope. */
+    readonly host?: string;
+    /** Default 0 → OS picks an unused port; resolve via address(). */
+    readonly port?: number;
+    /** Sync, called per request to fetch the currently-valid Bearer
+     *  token. Returning null → 401 token_unset (daemon has not generated
+     *  the token file yet, or rotated it). M1-18 daemon lifecycle wires
+     *  this to a cached token-file reader. */
+    readonly tokenSource: () => string | null;
+    readonly router: ControlRouterTarget;
+    /** agent name → that agent's DailyScheduler. Returning null →
+     *  schedule endpoint returns 404 not_found (rev3 fix #2 —
+     *  resolveScheduler helper enforces). */
+    readonly schedulerLookup?: (agentName: string) => DailyScheduler | null;
+    /** rev2 fix #4 — daemon source-of-truth current cfg reader. Used by
+     *  GET /schedule + POST /pause + POST /resume when the server's
+     *  internal lastSetSchedules cache misses (e.g. first POST /pause
+     *  after daemon startup with strategy.json initial schedule). May
+     *  return null when the agent has no configured schedule yet. */
+    readonly scheduleConfigLookup?: (agentName: string) => DailyScheduleConfig | null;
+    /** rev4 fix — daemon graceful stop callback. May return void or
+     *  Promise<void>. The server calls it via:
+     *    setImmediate(() => {
+     *      Promise.resolve()
+     *        .then(() => opts.onShutdown?.())
+     *        .catch((cause) => safeLog({code:"handler_threw", level:"error", cause, ...}));
+     *    });
+     *  so neither a synchronous throw NOR a rejected Promise can escape
+     *  as an unhandled rejection — both are funnelled through .catch
+     *  into safeLog. The client has already received the 200 response by
+     *  then, and the failure is logged via onLog without crashing the
+     *  server.
+     *
+     *  rev3 wrote this as `Promise.resolve(opts.onShutdown?.()).catch(...)`
+     *  which only caught async rejections — a synchronous throw escaped
+     *  the setImmediate callback because `opts.onShutdown?.()` is
+     *  evaluated BEFORE `Promise.resolve(...)` runs, so the throw never
+     *  reaches Promise.resolve at all. The corrected `.then(() => ...)`
+     *  shape relies on the standard Promise behavior that any throw
+     *  inside a `.then` callback is automatically converted to a
+     *  rejected Promise (and any returned rejected Promise is propagated),
+     *  so `.catch` reliably covers both shapes with one path. */
+    readonly onShutdown?: () => Promise<void> | void;
+    /** Called on lifecycle / request / auth events. Wrapped via safeLog
+     *  internally; throws are swallowed so a faulty logger cannot crash
+     *  the server (matches M1-15 onNotify pattern). */
+    readonly onLog?: (event: ControlLogEvent) => void;
+    /** Default 1_048_576 (1 MiB). parseJsonBody aborts and returns 413
+     *  payload_too_large past this; rev3 fix #4 requires the 413
+     *  response to be flushed BEFORE any best-effort req.destroy(),
+     *  so the client receives an HTTP 413 rather than ECONNRESET. */
+    readonly bodyLimitBytes?: number;
+    /** Defaults to a Date.now-backed clock; injectable for tests
+     *  (matches M1-15 SchedulerClock pattern). */
+    readonly clock?: {
+        readonly now: () => number;
+    };
+}
+export interface ControlServerAddress {
+    readonly host: string;
+    readonly port: number;
+}
+export interface ControlServer {
+    /** Bind host:port and resolve with the actual bound port. Throws
+     *  ControlServerError("invalid_state") when called twice or after
+     *  close(); rejects with ControlServerError("bind_failed") when
+     *  the OS rejects the bind (EADDRINUSE / EACCES / ...). */
+    listen(): Promise<number>;
+    /** Sync; returns null when the server has not yet listened. */
+    address(): ControlServerAddress | null;
+    /** Drain in-flight requests then close. Idempotent: pre-listen and
+     *  post-close calls resolve as no-ops. 5-second grace before forcing
+     *  remaining sockets shut via http.Server.closeAllConnections (Node
+     *  18.2+). */
+    close(): Promise<void>;
+}
+export type ControlServerErrorKind = "invalid_state" | "bind_failed";
+export declare class ControlServerError extends Error {
+    readonly name = "ControlServerError";
+    readonly kind: ControlServerErrorKind;
+    readonly cause: unknown;
+    constructor(kind: ControlServerErrorKind, message: string, cause?: unknown);
+}
+export type ControlErrorCode = "unauthorized" | "not_found" | "method_not_allowed" | "bad_request" | "unsupported_media_type" | "payload_too_large" | "not_implemented" | "service_unavailable" | "internal_error";
+export interface ControlErrorBody {
+    readonly error: {
+        readonly code: ControlErrorCode;
+        readonly message: string;
+        readonly details?: Readonly<Record<string, unknown>>;
+    };
+}
+export type { DailyScheduler, DailyScheduleConfig };

package/dist/types/daemon/agent-decision-adapter.d.ts

@@ -0,0 +1,40 @@
+import type { AgentDecisionProvider } from "../agents/agent";
+import type { ReconnectingWSClient, ReconnectingWSClientOptions } from "../wsclient/reconnect";
+import type { DecisionProvider } from "../decision/provider";
+import type { GameType, StrategyProfile } from "../decision/types";
+export interface GameStartCacheEntry {
+    readonly game: GameType;
+    readonly playerId: string;
+    readonly rules: unknown;
+}
+export type GameStartCache = Map<string, GameStartCacheEntry>;
+export declare function createGameStartCache(): GameStartCache;
+export type ReconnectFactory = (opts: ReconnectingWSClientOptions) => Promise<ReconnectingWSClient>;
+/**
+ * Builds a `connect` factory for `AgentInstanceOptions.connect`. It
+ * delegates to `createReconnectingWSClient(opts)` (or a caller-supplied
+ * factory for tests), then attaches a sidecar `client.onMessage` handler
+ * that snoops `game_start` envelopes and caches the immutable
+ * per-match metadata adapter.decide() needs later.
+ *
+ * The sidecar does NOT consume the message — wsclient still delivers it
+ * to the AgentInstance's own onMessage handler in parallel (M1-06
+ * sealed multi-handler API).
+ */
+export declare function buildConnectWithGameStartCache(cache: GameStartCache, factory?: ReconnectFactory): (opts: ReconnectingWSClientOptions) => Promise<ReconnectingWSClient>;
+export declare class AgentDecisionBridgeError extends Error {
+    readonly name = "AgentDecisionBridgeError";
+    readonly code: "missing_game_start_metadata";
+    readonly matchId: string;
+    constructor(matchId: string, message: string);
+}
+export interface BuildAgentDecisionAdapterOptions {
+    readonly provider: DecisionProvider;
+    readonly strategyProfile: StrategyProfile;
+    readonly cache: GameStartCache;
+    /** Subtracted from action_request.timeout_ms to derive the
+     *  decisionBudgetMs passed to M1-14 provider. Default 5000 ms. */
+    readonly decisionBudgetSafetyMs?: number;
+}
+export declare function buildAgentDecisionAdapter(opts: BuildAgentDecisionAdapterOptions): AgentDecisionProvider;
+export declare function buildLlmApiKeyResolver(agentName: string): (provider: string, model: string) => string;