@aifight/aifight 0.1.0-alpha.1

package/dist/types/reflection/proposal-store.d.ts

@@ -0,0 +1,50 @@
+import type { ReflectionProposal } from "./reflection-engine.js";
+export declare class ProposalStoreError extends Error {
+    readonly name = "ProposalStoreError";
+    readonly kind: "not_found" | "already_applied" | "patch_failed" | "validation_failed" | "io_error";
+    readonly cause?: unknown;
+    constructor(kind: ProposalStoreError["kind"], message: string, cause?: unknown);
+}
+/**
+ * Serialises a proposal to
+ * `~/.aifight/agents/<slug>/proposals/<timestamp>-<matchId>.proposal.json`.
+ *
+ * Creates the proposals directory if it does not exist.
+ * Returns the absolute path of the written file.
+ */
+export declare function saveProposal(agentSlug: string, proposal: ReflectionProposal): Promise<string>;
+export interface ListProposalsFilter {
+    status?: ReflectionProposal["status"];
+}
+/**
+ * Returns all proposals for an agent, optionally filtered by status.
+ * Results are sorted by createdAt ascending (oldest first).
+ * Returns [] when the proposals directory does not exist.
+ */
+export declare function listProposals(agentSlug: string, filter?: ListProposalsFilter): Promise<ReflectionProposal[]>;
+/**
+ * Reads a specific proposal by proposalId.
+ * Scans the proposals directory (linear scan; proposal counts are small).
+ * Throws ProposalStoreError("not_found") when no match is found.
+ */
+export declare function getProposal(agentSlug: string, proposalId: string): Promise<ReflectionProposal>;
+/**
+ * Applies a pending proposal to the agent's profile files.
+ *
+ * For each target:
+ *   - Reads the current file.
+ *   - Applies the patch (json_patch or text_replace).
+ *   - Validates the result (validateStrategy / validateSoul).
+ *   - Backs up the old file to versions/<name>.v<N>.<ext>.
+ *   - Atomically writes the new file.
+ *
+ * Updates the proposal status to "applied" and sets appliedAt.
+ * Throws ProposalStoreError on any failure (no partial writes on error).
+ */
+export declare function applyProposal(agentSlug: string, proposalId: string): Promise<void>;
+/**
+ * Marks a proposal as rejected without modifying any profile files.
+ * reason is ignored (proposals are immutable JSON; rejection just sets status).
+ */
+export declare function rejectProposal(agentSlug: string, proposalId: string, _reason?: string): Promise<void>;
+export type { ReflectionProposal, ProposalTarget } from "./reflection-engine.js";

package/dist/types/reflection/reflection-engine.d.ts

@@ -0,0 +1,81 @@
+/** One turn's decision, as stored in decisions.jsonl by the daemon. */
+export interface DecisionRecord {
+    /** Zero-based turn index within the match. */
+    turnIndex: number;
+    /** The action string that was ultimately submitted. */
+    selectedAction: string;
+    /** Whether the action was accepted by the server as legal. */
+    actionValid: boolean;
+    /** True when the LLM failed and the runtime fell back to heuristics. */
+    fallbackUsed: boolean;
+    /** Short prose summary of the LLM's stated reasoning, if captured. */
+    reasonSummary?: string;
+    /** Wall-clock ms from action_request receipt to action submission. */
+    latencyMs: number;
+}
+export interface MatchReflectionInput {
+    agentSlug: string;
+    matchId: string;
+    game: string;
+    result: "win" | "loss" | "draw";
+    ratingDelta: number;
+    newRating: number;
+    opponentName: string;
+    opponentModel?: string;
+    replayUrl: string;
+    /** All decisions recorded during the match (from decisions.jsonl). */
+    decisions: DecisionRecord[];
+    /** Raw event log from events.jsonl (opaque; used for pattern detection). */
+    events: unknown[];
+    totalCostUSD?: number;
+    totalLatencyMs?: number;
+}
+/**
+ * Generates a concise Markdown match recap suitable for writing to summary.md.
+ *
+ * Language: Chinese primary, English technical terms.
+ * Target length: ~20-35 lines regardless of match length.
+ */
+export declare function generateMatchSummary(input: MatchReflectionInput): string;
+export interface ProposalTarget {
+    /** Which file this patch applies to. */
+    file: "strategy.json" | "soul.md";
+    /**
+     * "json_patch" → patch is a JSON Patch array (RFC 6902).
+     * "text_replace" → patch is { old: string; new: string }.
+     */
+    type: "json_patch" | "text_replace";
+    patch: unknown;
+}
+export interface ReflectionProposal {
+    schemaVersion: 1;
+    /** UUID v4 generated at creation time. */
+    proposalId: string;
+    /** The daemon's session ID when the match was played. */
+    localSessionId: string;
+    agentSlug: string;
+    matchId: string;
+    targets: ProposalTarget[];
+    /** Human-readable explanation of why this proposal was generated. */
+    rationale: string;
+    /** Description of what could go wrong if applied. */
+    risk: string;
+    status: "pending" | "applied" | "rejected";
+    createdAt: string;
+    appliedAt?: string;
+}
+/**
+ * Analyses a completed match and produces a strategy improvement proposal,
+ * or returns null when no confident improvement can be identified.
+ *
+ * Heuristics (in priority order):
+ * 1. High fallback rate (>20%) → propose lowering riskAversion for the game
+ *    to avoid timeout-prone positions.
+ * 2. Loss with zero fallbacks → inspect riskAversion; if too aggressive
+ *    propose nudging it up slightly.
+ * 3. Win with high invalid-action rate → propose adding strategy notes.
+ * 4. Very slow average latency → propose a soul.md note on timeout awareness.
+ *
+ * Returns null when no heuristic fires with sufficient confidence.
+ */
+export declare function generateReflectionProposal(input: MatchReflectionInput, localSessionId?: string): ReflectionProposal | null;

package/dist/types/scheduler/daily.d.ts

@@ -0,0 +1,47 @@
+import type { AgentInstanceSnapshot } from "../agents/agent";
+import type { DailyScheduleConfig, DailySchedulerNotifyEvent, DailySchedulerSnapshot } from "./types";
+export interface SchedulerAgentTarget {
+    readonly name: string;
+    joinQueue(game: string, mode?: string): void;
+    snapshot(): AgentInstanceSnapshot;
+    onState(handler: (snapshot: AgentInstanceSnapshot) => void): () => void;
+}
+export type SchedulerTimerHandle = unknown;
+export interface SchedulerClock {
+    readonly now: () => number;
+    readonly setTimeout: (cb: () => void, ms: number) => SchedulerTimerHandle;
+    readonly clearTimeout: (h: SchedulerTimerHandle) => void;
+}
+export interface DailySchedulerOptions {
+    readonly agent: SchedulerAgentTarget;
+    /** Initial schedule snapshot taken once at construction; copied into
+     *  the scheduler's internal `currentSchedule` field. After construction
+     *  the only way to change schedule is `scheduler.setSchedule(cfg)`.
+     *  rev2 fix #3 single authority. */
+    readonly initialSchedule?: DailyScheduleConfig | null;
+    /** Optional health gate. Resolves true → join allowed; false / throw →
+     *  skip + notify. Scheduler does NOT hold a DecisionProvider instance
+     *  (rev1 decision #7). */
+    readonly healthCheck?: () => Promise<boolean>;
+    /** Default = real wall clock + globalThis.{setTimeout, clearTimeout}. */
+    readonly clock?: SchedulerClock;
+    readonly onNotify?: (event: DailySchedulerNotifyEvent) => void;
+}
+export interface DailyScheduler {
+    start(): void;
+    stop(): void;
+    snapshot(): DailySchedulerSnapshot;
+    /** rev2 fix #3 — single authority: replace internal `currentSchedule`.
+     *  `cfg` is sync-validated; invalid throws DailySchedulerError. `null`
+     *  means "no schedule" (scheduler keeps running; every fire goes to
+     *  skip_disabled). NOT equivalent to stop(). */
+    setSchedule(cfg: DailyScheduleConfig | null): void;
+}
+export type DailySchedulerErrorKind = "invalid_timezone" | "invalid_count" | "invalid_min_interval" | "invalid_state";
+export declare class DailySchedulerError extends Error {
+    readonly name = "DailySchedulerError";
+    readonly kind: DailySchedulerErrorKind;
+    readonly cause: unknown;
+    constructor(kind: DailySchedulerErrorKind, message: string, cause?: unknown);
+}
+export declare function createDailyScheduler(opts: DailySchedulerOptions): DailyScheduler;

package/dist/types/scheduler/types.d.ts

@@ -0,0 +1,42 @@
+import type { GameType } from "../decision/types";
+export interface DailyGameQuota {
+    /** Non-negative integer. 0 = this game is configured but not scheduled. */
+    readonly count: number;
+}
+export interface DailyScheduleConfig {
+    /** Master toggle. false → scheduler stays idle; existing config retained. */
+    readonly enabled: boolean;
+    /** IANA timezone name, e.g. "Asia/Shanghai" / "UTC". Day boundary is computed in this timezone. */
+    readonly timezone: string;
+    /** Per-game daily count. Empty object ⇔ disabled (no work). */
+    readonly days: Partial<Record<GameType, DailyGameQuota>>;
+    /** Minimum delay between any two `joinQueue` calls. Default 60. */
+    readonly minIntervalSec?: number;
+}
+export interface DailySchedulerSnapshot {
+    /** Whether start() has been called and stop() has not. */
+    readonly running: boolean;
+    /** Local YYYY-MM-DD in opts.config.timezone (or null when scheduler stopped). */
+    readonly today: string | null;
+    /** Remaining quota per game today (config.days minus today's fired count). */
+    readonly remaining: Partial<Record<GameType, number>>;
+    /** Most recent fire attempt outcome (or null pre-first-fire). */
+    readonly lastAttempt: DailySchedulerLastAttempt | null;
+    /** Estimated millis until next fire (relative to clock.now()), or null when no fire scheduled. */
+    readonly nextFireInMs: number | null;
+}
+export interface DailySchedulerLastAttempt {
+    readonly atMs: number;
+    readonly game: GameType;
+    readonly outcome: "join_succeeded" | "join_threw" | `skip_${string}`;
+    readonly cause?: unknown;
+}
+export interface DailySchedulerNotifyEvent {
+    readonly level: "info" | "warning" | "error";
+    readonly code: DailySchedulerNotifyCode;
+    readonly message: string;
+    readonly agent?: string;
+    readonly game?: GameType;
+    readonly cause?: unknown;
+}
+export type DailySchedulerNotifyCode = "started" | "stopped" | "schedule_changed" | "day_rolled_over" | "join_attempted" | "join_succeeded" | "join_threw" | "skip_disabled" | "skip_no_quota" | "skip_agent_not_started" | "skip_agent_stopped" | "skip_state_unavailable" | "skip_transport_disconnected" | "skip_state_busy" | "skip_min_interval" | "skip_health_check" | "health_check_threw" | "snapshot_threw" | "internal_error";

package/dist/types/session/match-session-manager.d.ts

@@ -0,0 +1,113 @@
+import type { UsageRecord } from "../llm/adapters/types.js";
+export type SessionStatus = "created" | "active" | "waiting_action" | "completed" | "abandoned";
+export interface MatchSession {
+    /** Locally generated UUID — stable across reconnects */
+    localSessionId: string;
+    /** Platform match ID from match_found / game_start */
+    platformMatchId: string;
+    /** Platform per-player session ID (present after game_start) */
+    platformSessionId?: string;
+    /** Agent slug (matches directory name) */
+    agentSlug: string;
+    /** Game identifier, e.g. "texas_holdem" */
+    gameId: string;
+    /** Environment tag: "production" | "beta" | "local" */
+    environment: string;
+    /** Lifecycle status */
+    status: SessionStatus;
+    /** SHA-256 of config.json at session creation time */
+    configHash: string;
+    /** SHA-256 of strategy.json (current game section) at session creation time */
+    strategyHash: string;
+    /** SHA-256 of soul.md at session creation time */
+    soulHash: string;
+    /** Provider profile ID used for this session */
+    providerProfileId: string;
+    /** ISO-8601 creation timestamp */
+    createdAt: string;
+    /** ISO-8601 last-update timestamp */
+    updatedAt: string;
+}
+export interface DecisionRecord {
+    /** Zero-based turn index within the match */
+    turnIndex: number;
+    /** Raw JSON string of legal actions array (stored as string to avoid parsing issues) */
+    legalActionsJson: string;
+    /** The action string returned to the platform */
+    selectedAction: string;
+    /** Whether the action passed platform validation */
+    actionValid: boolean;
+    /** True if a fallback action was used (LLM failed, timed out, or returned invalid) */
+    fallbackUsed: boolean;
+    /** Provider profile ID used for this decision */
+    providerProfileId: string;
+    /** Short one-line rationale extracted from LLM response (if available) */
+    reasonSummary?: string;
+    /** End-to-end decision latency in ms (LLM call + parse) */
+    latencyMs: number;
+    /** ISO-8601 timestamp */
+    timestamp: string;
+}
+/** Resolve the session directory for a given agent slug + match ID. */
+export declare function resolveSessionDir(agentSlug: string, matchId: string): string;
+export interface CreateSessionOpts {
+    platformMatchId: string;
+    platformSessionId?: string;
+    agentSlug: string;
+    gameId: string;
+    environment: string;
+    configHash: string;
+    strategyHash: string;
+    soulHash: string;
+    providerProfileId: string;
+}
+/**
+ * Creates the session directory and writes session.json.
+ * Returns the newly created MatchSession and the resolved session directory.
+ */
+export declare function createSession(opts: CreateSessionOpts): Promise<{
+    session: MatchSession;
+    sessionDir: string;
+}>;
+/**
+ * Loads an existing session from session.json.
+ * Throws if session.json is missing or malformed.
+ */
+export declare function loadSession(sessionDir: string): Promise<MatchSession>;
+/**
+ * Updates only the `status` and `updatedAt` fields of session.json.
+ */
+export declare function updateSessionStatus(sessionDir: string, status: SessionStatus): Promise<void>;
+/**
+ * Appends a raw platform event (any object) to events.jsonl.
+ * The event is stored as-is; no schema is enforced here.
+ */
+export declare function appendEvent(sessionDir: string, event: unknown): Promise<void>;
+/**
+ * Appends a decision record to decisions.jsonl.
+ */
+export declare function appendDecision(sessionDir: string, decision: DecisionRecord): Promise<void>;
+/**
+ * Appends a usage record to usage.jsonl.
+ */
+export declare function appendUsage(sessionDir: string, usage: UsageRecord): Promise<void>;
+/**
+ * Saves provider-specific continuation state (e.g. conversation thread IDs).
+ * Scoped to this match session only — never persisted globally.
+ */
+export declare function saveProviderState(sessionDir: string, state: unknown): Promise<void>;
+/**
+ * Loads provider continuation state.
+ * Returns null if provider-state.json does not exist yet.
+ */
+export declare function loadProviderState(sessionDir: string): Promise<unknown | null>;
+/**
+ * Writes the human-readable post-match summary to summary.md.
+ * Called once on game_over.
+ */
+export declare function writeSummary(sessionDir: string, summaryMd: string): Promise<void>;
+/**
+ * Lists all session directories for an agent, sorted by name (match ID).
+ * Returns absolute paths.
+ */
+export declare function listSessions(agentSlug: string): Promise<string[]>;

package/dist/types/session/session-context-builder.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The JSON object structure the LLM must return for every decision.
+ * Stored as a constant so it can be embedded verbatim in the prompt and
+ * referenced from tests without duplication.
+ */
+export declare const DECISION_OUTPUT_SCHEMA: {
+    readonly action: "string — exact action token from the legal_actions list";
+    readonly args: "object | null — action-specific parameters (omit or null if none required)";
+    readonly confidence: "number 0.0–1.0 — your confidence in this action being correct";
+    readonly reason_summary: "string — one short sentence: what you chose and the primary reason";
+    readonly risk_assessment: "low | medium | high — expected downside risk of this move";
+};
+export interface SessionContext {
+    /** Full system prompt (blocks 1–4 + 7: invariants, soul, strategy, anti-injection) */
+    systemPrompt: string;
+    /** Full user prompt (blocks 5–6: current state + legal actions + output contract) */
+    userPrompt: string;
+    /** Number of characters used by recent events (for diagnostics) */
+    recentEventsChars: number;
+    /** Whether recent events were truncated */
+    recentEventsTruncated: boolean;
+}
+export interface BuildSessionContextOpts {
+    /** Agent soul capsule: full text of soul.md */
+    soulMd: string;
+    /** Game strategy: the section of strategy.json relevant to this game (serialized) */
+    strategyText: string;
+    /** Game ID, e.g. "texas_holdem" */
+    gameId: string;
+    /** Platform match ID (for logging context, never injected into trusted block) */
+    platformMatchId: string;
+    /**
+     * Recent platform events from this session's events.jsonl, serialized to a
+     * human-readable string. The caller is responsible for summarizing / selecting
+     * which events to include. This text is wrapped in untrusted delimiters.
+     */
+    recentEventsText: string;
+    /**
+     * Current game state from the action_request message.
+     * Typically a JSON-serializable object; passed as JSON string.
+     */
+    currentStateJson: string;
+    /**
+     * Legal actions array from the action_request message.
+     * Must be a valid JSON array string.
+     */
+    legalActionsJson: string;
+    /** Turn index within the match (zero-based) */
+    turnIndex: number;
+    /** Provider profile ID (included in context for transparency) */
+    providerProfileId: string;
+}
+/**
+ * Assembles the complete system + user prompt pair for a single decision.
+ *
+ * Prompt assembly order:
+ *   System:
+ *     1. Invariant instructions (AIFight decision engine contract)
+ *     2. Agent soul capsule (soul.md)
+ *     3. Game strategy (strategy.json section for current game)
+ *     4. Anti-injection rule
+ *     7. Output contract (required JSON response schema)
+ *   User:
+ *     5. Match context (recent events from this session only)
+ *     6. Current state from platform (action_request.state)
+ *        + Legal actions (strict JSON array)
+ */
+export declare function buildSessionContext(opts: BuildSessionContextOpts): SessionContext;

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

@@ -0,0 +1,23 @@
+export type StoreErrorKind = "open" | "migration" | "query";
+export declare abstract class StoreError extends Error {
+    abstract readonly kind: StoreErrorKind;
+}
+export declare class StoreOpenError extends StoreError {
+    readonly kind: "open";
+    readonly path: string;
+    readonly cause?: unknown;
+    constructor(path: string, cause: unknown, message: string);
+}
+export declare class StoreMigrationError extends StoreError {
+    readonly kind: "migration";
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly cause?: unknown;
+    constructor(fromVersion: number, toVersion: number, cause: unknown, message: string);
+}
+export declare class StoreQueryError extends StoreError {
+    readonly kind: "query";
+    readonly sql: string;
+    readonly cause?: unknown;
+    constructor(sql: string, cause: unknown, message: string);
+}

package/dist/types/store/paths.d.ts

@@ -0,0 +1,3 @@
+export declare function getRuntimeHome(): string;
+export declare function getDefaultDbPath(): string;
+export declare function ensureRuntimeHome(): void;

package/dist/types/store/schema.generated.d.ts

@@ -0,0 +1 @@
+export declare const SCHEMA_SQL_V1 = "-- runtime/src/store/schema.sql\n-- AUTO-APPLIED by src/store/sqlite.ts as the v1 migration step.\n-- DO NOT edit this file by hand \u2014 this is v1's BYTE SOURCE (bundled\n-- into SCHEMA_SQL_V1 by bundle-schema.mjs). M1-05 appended a v2\n-- migration step inside sqlite.ts that re-creates the agents table\n-- with BLOB columns for encrypted api_key / claim_token. Current DB\n-- state after full migration: see sqlite.ts's \"Current schema (v2)\"\n-- header comment.\n--\n-- Tracked via `PRAGMA user_version`. This file defines user_version = 1;\n-- sqlite.ts's MIGRATIONS array brings it to 2.\n--\n-- OUT-OF-SCOPE for this file (DO NOT add here):\n--   * notifications  \u2014 v1.1.1 durable event stream (M2 when broker lands)\n--   * match_history  \u2014 M1-15 / M1-21\n--   * schedules      \u2014 M1-15\n--   * encrypted column DDL \u2014 lives in sqlite.ts's v2 migration step,\n--     NOT here (mutating this file would break SCHEMA_SQL_V1's byte\n--     identity and thus the v1 migration contract).\n--\n-- When adding a new migration in a later TED, APPEND a new migration\n-- step to sqlite.ts's MIGRATIONS array; DO NOT mutate this file's v1\n-- block. Past installs will keep their v1 body and only run the delta.\n\nCREATE TABLE IF NOT EXISTS agents (\n  id           TEXT NOT NULL PRIMARY KEY,             -- UUID v4 from server\n  name         TEXT NOT NULL UNIQUE,                   -- Public agent name\n  api_key      TEXT NOT NULL,                          -- v1 plaintext; v2 migration re-creates as BLOB\n  claim_token  TEXT NOT NULL,                          -- v1 plaintext; v2 migration re-creates as BLOB\n  model        TEXT NOT NULL DEFAULT '',\n  created_at   INTEGER NOT NULL,                       -- unix ms\n  updated_at   INTEGER NOT NULL                        -- unix ms\n);\n\nCREATE INDEX IF NOT EXISTS idx_agents_name ON agents(name);\n";

package/dist/types/store/sqlite.d.ts

@@ -0,0 +1,36 @@
+import type { Database as DatabaseType } from "better-sqlite3";
+export interface OpenDatabaseOptions {
+    /** Default: getDefaultDbPath(). Pass ":memory:" for tests. */
+    path?: string;
+    /** Skip ensureRuntimeHome(); tests with in-memory or mkdtemp DBs use this. */
+    skipEnsureHome?: boolean;
+    /** Override CURRENT_SCHEMA_VERSION. Tests use this to assert
+     *  downgrade-detection. Production callers MUST omit. */
+    targetVersion?: number;
+}
+export interface AgentRow {
+    id: string;
+    name: string;
+    /** Encrypted BLOB; produced by account/credentials.ts#encryptForStorage. */
+    api_key: Buffer;
+    /** Encrypted BLOB; produced by account/credentials.ts#encryptForStorage. */
+    claim_token: Buffer;
+    model: string;
+    created_at: number;
+    updated_at: number;
+}
+export type UpsertAgentInput = Omit<AgentRow, "created_at" | "updated_at"> & {
+    created_at?: number;
+    updated_at?: number;
+};
+export interface StoreHandle {
+    readonly path: string;
+    readonly schemaVersion: number;
+    close(): void;
+    getAgentByName(name: string): AgentRow | undefined;
+    upsertAgent(row: UpsertAgentInput): AgentRow;
+    listAgents(): AgentRow[];
+    deleteAgent(name: string): boolean;
+    raw(): DatabaseType;
+}
+export declare function openDatabase(opts?: OpenDatabaseOptions): StoreHandle;