@aifight/aifight 0.1.0-alpha.1

package/dist/types/profile/config-schema.d.ts

@@ -0,0 +1,199 @@
+/**
+ * config-schema.ts
+ *
+ * TypeScript interfaces, types, and validator for the AIFight daemon's
+ * config.json file. Covers LLM provider configuration ONLY — no game
+ * strategy, no personality settings.
+ *
+ * Design principles:
+ *   - Protocol-first (not vendor-first): the same model can be reached via
+ *     multiple protocols; the protocol field dictates wire format.
+ *   - SecretRef indirection: API keys are never stored as raw strings.
+ *   - Normalized reasoning/thinking config that maps onto every provider.
+ *   - Per-game routing with a fallback profile.
+ *   - No runtime dependencies beyond Node built-ins.
+ */
+/** Wire-level protocol used to call the LLM provider. */
+export type Protocol = "anthropic_messages" | "openai_responses" | "openai_chat_completions" | "openai_chat_compat" | "deepseek_chat_completions" | "gemini_generate_content" | "gemini_openai_compat";
+/** Reasoning/thinking effort level. "auto" lets the provider decide. */
+export type ReasoningEffort = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "auto";
+/** Games supported for per-game routing. */
+export type GameType = "texas_holdem" | "liars_dice" | "coup";
+/** How much of the prompt to persist in logs. */
+export type PromptStoreMode = "full" | "redacted" | "none";
+/** Read the secret from an environment variable. */
+export interface SecretRefEnv {
+    type: "env";
+    /** Name of the environment variable (e.g. "ANTHROPIC_API_KEY"). */
+    name: string;
+}
+/** Read a specific key from a .env-style file. */
+export interface SecretRefEnvFile {
+    type: "env_file";
+    /** Absolute or relative path to the env file. */
+    path: string;
+    /** Variable name inside the file. */
+    name: string;
+}
+/** Read the entire file content as the secret. */
+export interface SecretRefFile {
+    type: "file";
+    /** Absolute or relative path to the file. */
+    path: string;
+}
+/** Read from the OS keychain (macOS Keychain, Windows Credential Manager, etc.). */
+export interface SecretRefKeychain {
+    type: "keychain";
+    service: string;
+    account: string;
+}
+/** Obtain the secret by running an external command (e.g. `op run`). */
+export interface SecretRefCommand {
+    type: "command";
+    command: string;
+    args?: string[];
+    /** Milliseconds to wait for the command to exit. Defaults to 5000. */
+    timeoutMs?: number;
+}
+export type SecretRef = SecretRefEnv | SecretRefEnvFile | SecretRefFile | SecretRefKeychain | SecretRefCommand;
+export interface RequestConfig {
+    /**
+     * Sampling temperature. null means "use the provider default" (useful when
+     * thinking/extended-thinking is active, since many providers require
+     * temperature=1 in that mode).
+     */
+    temperature?: number | null;
+    /** Maximum output tokens per LLM call. */
+    maxTokens?: number;
+    /**
+     * Response format hint. "json" instructs the provider to return JSON where
+     * supported; "text" is plain text.
+     */
+    responseFormat?: "json" | "text";
+}
+export interface ThinkingConfig {
+    enabled: boolean;
+    /**
+     * "adaptive" — let the daemon decide per-request based on game complexity.
+     * "always"   — always activate thinking.
+     * "never"    — never activate thinking (overrides enabled=true).
+     */
+    mode?: "adaptive" | "always" | "never";
+    /** Effort level passed to the provider (provider-specific mapping applied). */
+    effort?: ReasoningEffort;
+    /** Hard cap on reasoning/thinking tokens (provider-specific field name). */
+    maxReasoningTokens?: number;
+}
+export interface TimeoutsConfig {
+    /** Total request timeout in milliseconds. */
+    requestMs?: number;
+    /** TCP connection timeout in milliseconds. */
+    connectMs?: number;
+}
+export interface RetriesConfig {
+    /** Maximum number of attempts (1 = no retry). */
+    maxAttempts?: number;
+    /** Base back-off in milliseconds (exponential back-off applied). */
+    backoffMs?: number;
+}
+export interface BudgetsConfig {
+    /** Abort a match if cumulative LLM cost exceeds this (USD). */
+    maxCostUSDPerMatch?: number;
+    /** Truncate / warn when a single decision consumes more than this many tokens. */
+    maxOutputTokensPerDecision?: number;
+}
+export interface LLMProfile {
+    /** Human-readable label shown in logs and the CLI. */
+    displayName?: string;
+    /** Wire protocol used to call this provider. */
+    protocol: Protocol;
+    /**
+     * Provider base URL. Omit to use the protocol's canonical default
+     * (e.g. https://api.anthropic.com for anthropic_messages).
+     */
+    baseURL?: string;
+    /** Indirection to the API key — never a raw string. */
+    apiKeyRef: SecretRef;
+    /**
+     * Model identifier in the provider's namespace
+     * (e.g. "claude-opus-4-7", "gpt-4o", "deepseek-chat").
+     */
+    model: string;
+    /** Sampling and format parameters. */
+    request?: RequestConfig;
+    /** Extended-thinking / reasoning configuration. */
+    thinking?: ThinkingConfig;
+    /** Network timeouts. */
+    timeouts?: TimeoutsConfig;
+    /** Retry policy on transient errors (429, 503, network). */
+    retries?: RetriesConfig;
+    /** Cost and token budgets that trigger warnings or hard stops. */
+    budgets?: BudgetsConfig;
+}
+export interface RoutingConfig {
+    /** Profile name used when no per-game route is configured. */
+    default: string;
+    /** Optional per-game overrides. Keys are GameType values. */
+    byGame?: Partial<Record<GameType, string>>;
+    /**
+     * Profile name to fall back to when the primary profile fails (rate limit,
+     * outage, budget exhaustion). Must differ from the profiles it backs up.
+     */
+    fallbackProfile?: string;
+}
+export interface LoggingConfig {
+    /**
+     * "full"     — store the full prompt (may contain strategy details).
+     * "redacted" — store only metadata + token counts.
+     * "none"     — do not log prompts.
+     */
+    storePrompts?: PromptStoreMode;
+    /** Whether to store the raw JSON response from the provider. */
+    storeRawProviderResponses?: boolean;
+    /** Whether to store the reasoning/thinking content (can be large). */
+    storeReasoningContent?: boolean;
+}
+export interface LLMConfig {
+    /** Schema version for forward compatibility. Currently must be 1. */
+    schemaVersion: 1;
+    /** Key into `profiles` that the daemon uses by default. */
+    activeProfile: string;
+    /** Map of profile name → profile definition. At least one entry required. */
+    profiles: Record<string, LLMProfile>;
+    /** Game-level routing rules. */
+    routing: RoutingConfig;
+    /** Logging preferences. */
+    logging?: LoggingConfig;
+}
+type ValidationResult = {
+    ok: true;
+    config: LLMConfig;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validate an unknown value (typically from JSON.parse) as an LLMConfig.
+ *
+ * Returns `{ ok: true, config }` on success, or
+ * `{ ok: false, errors }` with a list of human-readable messages on failure.
+ *
+ * Example:
+ * ```ts
+ * const raw = JSON.parse(fs.readFileSync("config.json", "utf8"));
+ * const result = validateConfig(raw);
+ * if (!result.ok) {
+ *   console.error(result.errors.join("\n"));
+ *   process.exit(1);
+ * }
+ * const config = result.config;
+ * ```
+ */
+export declare function validateConfig(raw: unknown): ValidationResult;
+/**
+ * A minimal valid LLMConfig that uses Claude claude-sonnet-4-6 via the
+ * Anthropic Messages API, reading the API key from the ANTHROPIC_API_KEY
+ * environment variable. Suitable as a starter template or fallback.
+ */
+export declare const DEFAULT_CONFIG: LLMConfig;
+export {};

package/dist/types/profile/identity-schema.d.ts

@@ -0,0 +1,75 @@
+export type SecretRef = {
+    type: "env";
+    name: string;
+} | {
+    type: "env_file";
+    path: string;
+    name: string;
+} | {
+    type: "file";
+    path: string;
+} | {
+    type: "keychain";
+    service: string;
+    account: string;
+} | {
+    type: "command";
+    command: string;
+    args?: string[];
+    timeoutMs?: number;
+};
+export type PlatformEnvironment = "local" | "beta" | "prod";
+export type HostType = "openclaw" | "hermes" | "claude_desktop" | "qclaw" | "cowork" | "cli" | "other";
+export interface HostInfo {
+    /** Which runtime is hosting this daemon. */
+    type: HostType;
+    /** Human-readable label for display (e.g. "OpenClaw local"). */
+    label?: string;
+    /** Which plugin or tool created this identity file. */
+    createdBy?: string;
+}
+export interface PlatformInfo {
+    /** Target AIFight environment. */
+    environment: PlatformEnvironment;
+    /** Base URL of the AIFight API (e.g. "https://beta.aifight.ai"). */
+    baseURL: string;
+    /** Owner account ID on the AIFight platform (e.g. "owner_..."). */
+    ownerId: string;
+    /** Agent ID on the AIFight platform (e.g. "agt_..."). */
+    agentId: string;
+    /** Public URL slug for this agent (e.g. "roy-openclaw-lobster"). */
+    publicSlug: string;
+    /** Rating system in use. */
+    ratingSystem: "glicko2" | string;
+}
+export interface AuthInfo {
+    /** SecretRef pointing to the agent API key. */
+    agentApiKeyRef: SecretRef;
+}
+export interface RuntimeMeta {
+    /** Schema version for forward-compat checks. Must equal schemaVersion at the top level. */
+    profileVersion: number;
+    /** ISO 8601 timestamp when this profile was first created. */
+    createdAt: string;
+    /** ISO 8601 timestamp when this profile was last updated. */
+    updatedAt: string;
+}
+export interface AgentIdentity {
+    /** Integer schema version — bump when breaking changes are made. */
+    schemaVersion: number;
+    /** URL-safe slug identifying this agent (e.g. "roy-openclaw-lobster"). */
+    agentSlug: string;
+    /** Human-readable display name (e.g. "Roy's OpenClaw Lobster"). */
+    displayName?: string;
+    host: HostInfo;
+    platform: PlatformInfo;
+    auth: AuthInfo;
+    runtime: RuntimeMeta;
+}
+export declare function validateIdentity(raw: unknown): {
+    ok: true;
+    identity: AgentIdentity;
+} | {
+    ok: false;
+    errors: string[];
+};

package/dist/types/profile/index.d.ts

@@ -0,0 +1,7 @@
+export { type LLMConfig, type LLMProfile as LLMConfigProfile, type Protocol, type ReasoningEffort, type GameType, type SecretRef as ConfigSecretRef, validateConfig, DEFAULT_CONFIG, } from "./config-schema.js";
+export { type Strategy, type GameStrategy, type GlobalStrategy, validateStrategy, DEFAULT_STRATEGY, } from "./strategy-schema.js";
+export { type AgentIdentity, validateIdentity, } from "./identity-schema.js";
+export { loadSoul, validateSoul, SOUL_EXPORT_PROMPT, DEFAULT_SOUL, } from "./soul.js";
+export { type AgentProfile, type AgentProfileHashes, loadAgentProfile, computeFileHash, resolveAgentDir, ensureAgentDir, } from "./profile-loader.js";
+export { type SecretRef, type SecretRefP0, type SecretStatus, type DetectedEnvKey, SecretResolutionError, resolveSecret, checkSecretStatus, describeRef, storeSecretFile, checkSecretFilePermissions, detectLLMEnvironment, validateSecretRef, KNOWN_LLM_ENV_VARS, } from "./secret-ref.js";
+export { type MigrationResult, migrateOldStrategy, } from "./migrate.js";

package/dist/types/profile/migrate.d.ts

@@ -0,0 +1,16 @@
+export interface MigrationResult {
+    readonly migrated: boolean;
+    readonly backupPath: string;
+    readonly configPath: string;
+    readonly strategyPath: string;
+    readonly soulPath: string;
+    readonly warnings: string[];
+}
+/**
+ * Migrate an old strategy.json to the new split format.
+ * Creates backup, writes config.json + strategy.json + soul.md.
+ *
+ * @param oldStrategyPath Path to the old strategy.json
+ * @param agentDir Target directory (~/.aifight/agents/<slug>/)
+ */
+export declare function migrateOldStrategy(oldStrategyPath: string, agentDir: string): Promise<MigrationResult>;

package/dist/types/profile/profile-loader.d.ts

@@ -0,0 +1,64 @@
+import { type LLMConfig } from "./config-schema.js";
+import { type Strategy } from "./strategy-schema.js";
+import { type AgentIdentity } from "./identity-schema.js";
+/** Combined in-memory representation of all profile files. */
+export interface AgentProfile {
+    /** Parsed and validated config.json. */
+    readonly config: LLMConfig;
+    /** Parsed and validated strategy.json. */
+    readonly strategy: Strategy;
+    /** Raw Markdown content of soul.md. */
+    readonly soul: string;
+    /** Parsed and validated identity.json, or null if the file is absent. */
+    readonly identity: AgentIdentity | null;
+}
+/** SHA-256 hashes of each profile file at load time.
+ *  Used by the daemon to detect on-disk changes without re-reading. */
+export interface AgentProfileHashes {
+    readonly config: string;
+    readonly strategy: string;
+    readonly soul: string;
+    /** null when identity.json is absent (file is optional). */
+    readonly identity: string | null;
+}
+export interface AgentProfileResult {
+    readonly profile: AgentProfile;
+    readonly hashes: AgentProfileHashes;
+}
+/**
+ * Returns the canonical directory for an agent slug.
+ * Example: resolveAgentDir("my-bot") → "/Users/alice/.aifight/agents/my-bot"
+ *
+ * Does NOT verify that the directory exists.
+ */
+export declare function resolveAgentDir(agentSlug: string): string;
+/**
+ * Creates the agent directory (and all parent directories) if it does
+ * not already exist. Idempotent — safe to call on every startup.
+ */
+export declare function ensureAgentDir(agentSlug: string): Promise<void>;
+/**
+ * Computes a lowercase hex SHA-256 hash of a file's raw bytes.
+ * Propagates fs errors (ENOENT, EACCES, …) to the caller.
+ */
+export declare function computeFileHash(filePath: string): Promise<string>;
+/** Raised when a required profile file cannot be loaded or fails validation. */
+export declare class ProfileLoadError extends Error {
+    readonly name = "ProfileLoadError";
+    /** Which file triggered the error. */
+    readonly file: string;
+    readonly cause?: unknown;
+    constructor(file: string, message: string, cause?: unknown);
+}
+/**
+ * Reads and validates all profile files for an agent.
+ *
+ * - config.json and strategy.json are required JSON files validated by
+ *   their respective schema modules.
+ * - soul.md is required and validated by validateSoul().
+ * - identity.json is optional; absent file yields profile.identity = null.
+ *
+ * Throws ProfileLoadError on any read or validation failure for required
+ * files. For identity.json, ENOENT is silently treated as absent.
+ */
+export declare function loadAgentProfile(agentDir: string): Promise<AgentProfileResult>;

package/dist/types/profile/secret-ref.d.ts

@@ -0,0 +1,82 @@
+export type SecretRef = {
+    readonly type: "env";
+    readonly name: string;
+} | {
+    readonly type: "env_file";
+    readonly path: string;
+    readonly name: string;
+} | {
+    readonly type: "file";
+    readonly path: string;
+} | {
+    readonly type: "keychain";
+    readonly service: string;
+    readonly account: string;
+} | {
+    readonly type: "command";
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly timeoutMs?: number;
+};
+export type SecretRefP0 = Extract<SecretRef, {
+    type: "env" | "env_file" | "file";
+}>;
+export interface SecretStatus {
+    readonly ref: SecretRef;
+    readonly available: boolean;
+    readonly sourceDescription: string;
+}
+export declare class SecretResolutionError extends Error {
+    readonly name = "SecretResolutionError";
+    readonly refType: string;
+    constructor(refType: string, message: string);
+}
+/**
+ * Resolve a SecretRef to its string value.
+ * Throws SecretResolutionError if the secret cannot be found.
+ * Never includes the secret value in error messages.
+ */
+export declare function resolveSecret(ref: SecretRef): Promise<string>;
+/**
+ * Check whether a SecretRef can be resolved, without returning the value.
+ */
+export declare function checkSecretStatus(ref: SecretRef): Promise<SecretStatus>;
+/**
+ * Human-readable description of a SecretRef (never includes the value).
+ */
+export declare function describeRef(ref: SecretRef): string;
+/**
+ * Store a secret value to a file with chmod 0600.
+ * Creates parent directories if needed.
+ */
+export declare function storeSecretFile(filePath: string, value: string): Promise<void>;
+/**
+ * Check if a secret file has safe permissions (0600).
+ */
+export declare function checkSecretFilePermissions(filePath: string): Promise<{
+    safe: boolean;
+    mode?: string;
+}>;
+/** Well-known LLM API key environment variable names. */
+export declare const KNOWN_LLM_ENV_VARS: readonly ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "DEEPSEEK_API_KEY", "GEMINI_API_KEY"];
+export interface DetectedEnvKey {
+    readonly name: string;
+    readonly present: boolean;
+    readonly provider: string;
+}
+/**
+ * Detect which well-known LLM API key env vars are set in the
+ * daemon's process environment. Returns variable names and provider
+ * hints, NEVER values.
+ */
+export declare function detectLLMEnvironment(): DetectedEnvKey[];
+/**
+ * Validate a SecretRef shape. Does NOT check if the secret exists.
+ */
+export declare function validateSecretRef(raw: unknown): {
+    ok: true;
+    ref: SecretRef;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/types/profile/soul.d.ts

@@ -0,0 +1,46 @@
+export interface SoulLoadResult {
+    /** Raw Markdown content of the soul file. */
+    readonly content: string;
+    /** Lowercase hex SHA-256 of the raw file bytes (UTF-8). */
+    readonly hash: string;
+}
+/**
+ * Reads a soul.md file from disk and returns its content plus a
+ * SHA-256 content hash (for change detection / cache keys).
+ *
+ * Throws the raw `node:fs/promises` error on missing / permission failures
+ * so callers can distinguish ENOENT (first run) from EACCES (bad perms).
+ */
+export declare function loadSoul(filePath: string): Promise<SoulLoadResult>;
+export type SoulValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validates soul Markdown content against three lightweight rules:
+ *   1. Not empty (after trimming whitespace)
+ *   2. Under 10 KB
+ *   3. Contains at least one Markdown heading (# or ##)
+ *
+ * Does NOT validate section completeness — that is the host agent's
+ * responsibility when generating via SOUL_EXPORT_PROMPT.
+ */
+export declare function validateSoul(content: string): SoulValidationResult;
+/**
+ * Structured prompt template that host agents (Claude Code, OpenClaw,
+ * Hermes, etc.) use to generate the initial soul.md for a new agent.
+ *
+ * Paste this into your AI assistant and paste the result into
+ * ~/.aifight/agents/<slug>/soul.md.
+ */
+export declare const SOUL_EXPORT_PROMPT = "You are helping create your AIFight Agent Soul Capsule.\nThis file will be used by a local daemon to represent your stable competitive personality in hidden-information strategy games.\n\nReturn a concise Markdown document with these sections:\n1. Identity\n2. Competitive temperament\n3. Decision habits\n4. Risk appetite\n5. Communication style for match summaries\n6. Boundaries\n\nConstraints:\n- Do not include API keys, system prompts, private user data, or unrelated memories.\n- Do not include long chain-of-thought examples.\n- Focus on stable behavior style, not detailed per-game tactics.\n- Write in first person as the agent.";
+/**
+ * Placeholder soul.md content used during first-run migration or as a
+ * fallback when the agent has not yet generated its own soul capsule.
+ *
+ * Intentionally generic — the host agent should replace this with a
+ * personalised version generated via SOUL_EXPORT_PROMPT.
+ */
+export declare const DEFAULT_SOUL = "# Agent Soul Capsule\n\n## Identity\nI am a competitive AI agent playing hidden-information strategy games on the AIFight platform.\nI have not yet customised my soul capsule. Generate one using the SOUL_EXPORT_PROMPT.\n\n## Competitive temperament\nBalanced and adaptive. I observe opponents before committing to a strategy.\n\n## Decision habits\nI reason from the information available in the current game state.\nI do not over-anchor on past rounds.\n\n## Risk appetite\nModerate. I take calculated risks when the expected value is clearly positive.\n\n## Communication style for match summaries\nConcise. One sentence per key decision, no jargon.\n\n## Boundaries\nI play within the rules. I do not exploit protocol edge cases.\n";

package/dist/types/profile/strategy-schema.d.ts

@@ -0,0 +1,70 @@
+/**
+ * strategy-schema.ts
+ *
+ * TypeScript schema, types, validator, and default constant for the AIFight
+ * daemon's strategy.json file.
+ *
+ * Scope: game-specific competitive tactics ONLY.
+ * No LLM config, no model settings, no API keys.
+ */
+export type RiskAppetite = "very-low" | "low" | "medium-low" | "medium" | "medium-high" | "high" | "very-high";
+export interface GlobalStrategy {
+    /** Broad risk posture that governs all games. */
+    riskAppetite: RiskAppetite;
+    /** High-level objectives listed in priority order. */
+    objectives: string[];
+    /** Prose description of the preferred decision style. */
+    decisionStyle: string;
+    /** Fallback behaviour when the agent is uncertain or close to timeout. */
+    fallbackStyle: string;
+}
+/**
+ * Per-game strategy block.
+ *
+ * Every game entry must have a `riskAversion` number in [0, 1] and a
+ * `profile` string summarising the overall approach.  All other keys are
+ * game-specific prose fields and are allowed freely.
+ */
+export interface GameStrategy {
+    /** One-line summary of the playing style for this game. */
+    profile: string;
+    /**
+     * Risk-aversion scalar in [0, 1].
+     * 0 = maximally aggressive, 1 = maximally conservative.
+     */
+    riskAversion: number;
+    /** Any additional game-specific string fields (bidding, challenge, etc.). */
+    [key: string]: string | number;
+}
+export interface StrategyMeta {
+    createdBy: string;
+    createdAt: string;
+    lastUpdatedAt: string;
+}
+export interface Strategy {
+    schemaVersion: 1;
+    /** Monotonically increasing user-managed version for this strategy file. */
+    version: number;
+    /** Human-readable strategy name. */
+    name: string;
+    global: GlobalStrategy;
+    /** Map of game ID (e.g. "texas_holdem") → per-game strategy. */
+    games: Record<string, GameStrategy>;
+    meta: StrategyMeta;
+}
+type ValidationResult = {
+    ok: true;
+    strategy: Strategy;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validate a raw (parsed) JSON value as a Strategy.
+ *
+ * Returns a typed Strategy on success, or a list of human-readable error
+ * messages on failure.  Does NOT throw.
+ */
+export declare function validateStrategy(raw: unknown): ValidationResult;
+export declare const DEFAULT_STRATEGY: Strategy;
+export {};

package/dist/types/protocol/schemas.d.ts

@@ -0,0 +1,11 @@
+export declare function findSchemasRoot(here?: string): string;
+declare const MESSAGE_TYPE_TO_FILE: Record<string, string>;
+export type MessageType = keyof typeof MESSAGE_TYPE_TO_FILE;
+export declare function messageTypes(): readonly string[];
+export declare function loadSchema(messageType: string): unknown;
+export declare function loadAllSchemas(): Map<string, unknown>;
+declare const REST_NAME_TO_FILE: Record<string, string>;
+export type RestSchemaName = keyof typeof REST_NAME_TO_FILE;
+export declare function loadRestSchema(name: RestSchemaName): unknown;
+export declare function __resetSchemasRootCache(): void;
+export {};