kestrel.markets
Version:
A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.
117 lines • 7.48 kB
TypeScript
/**
* IB Gateway transport configuration — **entirely env-driven, zero secret hardcoding**, mirroring
* the lake accessor's discipline (`src/adapters/lake/config.ts`): no credential is ever baked into
* source; the account id (a sensitive identifier) is held in memory only, never logged, and is
* REDACTED in every surfaced diagnostic (as the lake redacts secrets from surfaced SQL).
*
* The IB TWS socket API has NO in-band password — a human logs the IB Gateway in out-of-band; the
* transport only speaks to that CLIENT-LAUNCHED local gateway. Host/port therefore default to the
* loopback + IB's own publicly-documented paper-gateway port (4002) — these reveal nothing about
* any strategy, infrastructure, or account, so they are publication-safe defaults, not a baked
* endpoint. The account id has NO default: it is either supplied or discovered from the gateway's
* `managedAccounts` handshake.
*
* ## Resolution precedence (first present wins)
* 1. explicit {@link IbkrConfigInput} override passed to {@link resolveIbkrConfig}
* 2. process environment
* 3. a publication-safe default (loopback host, IB paper port, clientId 0, paper mode)
*
* ## Environment
* - `KESTREL_IBKR_HOST` — gateway host (default `127.0.0.1`; the client-launched local gateway)
* - `KESTREL_IBKR_PORT` — gateway API port (default `4002`, IB Gateway paper; live/TWS differ)
* - `KESTREL_IBKR_CLIENT_ID` — unique API client id per gateway instance (default `0`)
* - `KESTREL_IBKR_ACCOUNT` — account id to pin (default: discovered from `managedAccounts`)
* - `KESTREL_IBKR_MODE` — `paper` | `live` Kestrel mode gate (default `paper`; live refused here)
*
* ## Mode gate (ADR-0034 §a, owner-reviewed)
* `paper` is a **Kestrel-enforced mode gate**, not merely a port/account fact. This transport bead
* places NO orders and ships NO live routing, so a `live` mode resolves but the transport REFUSES
* to connect in it (fail-closed, {@link IbkrConnectionError} `mode-gate`). Live authority is a
* human-signed arm behind a separate bead (kestrel-7o2.9/7o2.10), never a config flag.
*/
/** The closed Kestrel mode vocabulary this transport honors. `paper` is the enforced default; `live`
* resolves but is refused at connect time in this bead (no live routing ships here). */
export type IbkrMode = "paper" | "live";
/** Publication-safe defaults — loopback + IB's own documented paper port. NOT a baked endpoint:
* these reveal no strategy/infra/account, and are always overridable by env/override. */
export declare const IBKR_DEFAULT_HOST = "127.0.0.1";
export declare const IBKR_DEFAULT_PORT = 4002;
export declare const IBKR_DEFAULT_CLIENT_ID = 0;
export declare const IBKR_DEFAULT_MODE: IbkrMode;
/** Fully-resolved transport config. `account` is `undefined` when neither supplied nor yet
* discovered from the gateway handshake; it is a SENSITIVE identifier — redact it in diagnostics. */
export interface IbkrConfig {
readonly host: string;
readonly port: number;
readonly clientId: number;
/** Pinned account id, or `undefined` to accept whatever the gateway's `managedAccounts` reports. */
readonly account: string | undefined;
/** The Kestrel mode gate. `live` is refused by the transport in this bead (fail-closed). */
readonly mode: IbkrMode;
}
/** Caller override: any subset wins over the environment; omitted fields fall through to env then
* the publication-safe default. */
export interface IbkrConfigInput {
host?: string;
port?: number;
clientId?: number;
account?: string;
mode?: IbkrMode;
/** Environment to read from; defaults to `process.env` (injected for tests — no ambient env). */
env?: Record<string, string | undefined>;
}
/**
* Resolve the effective {@link IbkrConfig} from override > env > publication-safe default. Pure and
* zero-network: it only reads the injected/ambient environment. Throws {@link IbkrConfigError} only
* for a PRESENT-but-malformed value (a non-integer port, an unknown mode) — never for an absent one
* (defaults cover absence). No credential is ever baked in; the account id, if present, is held on
* the returned object in memory only.
*/
export declare function resolveIbkrConfig(input?: IbkrConfigInput): IbkrConfig;
/**
* What KIND of IB account the gateway's `managedAccounts` handshake reported — the input to
* ADR-0034 §3's promised SECOND barrier ("the broker's paper/live account is defense-in-depth …
* reaching the right one is a useful *second* barrier"). The Kestrel mode gate stays the PRIMARY
* control; this is the backstop that catches what the mode gate structurally cannot see — a
* misconfigured port or a fat-fingered endpoint that lands on a LIVE-logged-in gateway while every
* mode string still reads `paper`.
*
* - `paper` — an IB paper account (`DU…` individual, `DF…` advisor).
* - `live` — an IB live, real-money account (`U…`).
* - `unknown` — anything else: absent, empty, or a shape this vocabulary does not recognise. It is a
* DISTINCT member and NOT a synonym for `paper`: an account we cannot classify is refused exactly
* as loudly as a live one (AGENTS: never a silent default — an unclassifiable account is not
* evidence of a paper account).
*/
export type IbkrAccountClass = "paper" | "live" | "unknown";
/**
* Classify an IB account id by its prefix — PURE, zero-network, and secret-free (it never returns,
* logs, or embeds the id). FAIL CLOSED by construction: it only ever answers `paper` for a shape it
* POSITIVELY recognises as a paper account; everything it does not recognise is `unknown`, which the
* caller must refuse. There is deliberately no case-normalisation and no prefix-only match: IB emits
* these ids uppercase and digit-suffixed, so a value that does not match that shape is precisely the
* value we must not be guessing about.
*/
export declare function classifyIbkrAccount(account: string | undefined): IbkrAccountClass;
/**
* IB's own publicly-documented REAL-MONEY API ports, and what listens on each. Defense-in-depth ONLY:
* the load-bearing barrier is {@link classifyIbkrAccount} against the account the handshake actually
* reported, because a live gateway can be moved to any port at all and a port number is only ever a
* claim about an endpoint, never evidence about an account. This map catches the fat-finger EARLY,
* before a socket is opened; the account assertion catches everything, including a nonstandard one.
*/
export declare const IBKR_LIVE_PORTS: ReadonlyMap<number, string>;
/**
* Redact a sensitive account id for logs/diagnostics (kestrel-7o2.5) — keep only the leading char
* and the last two so an operator can recognize their own account without the full number ever
* reaching a log/error/report. `undefined`/short ids collapse to a fixed mask. As the lake redacts
* secrets from surfaced SQL, the transport redacts the account from every surfaced string.
*/
export declare function redactAccount(account: string | undefined): string;
/**
* A publication-safe, secret-free description of a resolved config for logs/diagnostics
* (kestrel-7o2.5). The account is REDACTED via {@link redactAccount}; host/port/clientId/mode carry
* no secret. This is the ONLY string form of a config that may ever be logged or surfaced.
*/
export declare function describeIbkrConfig(config: IbkrConfig): string;
//# sourceMappingURL=config.d.ts.map