"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
import i18n from "@/i18n";
import { authHeaders, withAuthTicket } from "@/lib/apiAuth";
import type {
OptionsChainResponse,
OptionsPayoffRequest,
OptionsPayoffResponse,
} from "@/lib/options";
const BASE = "";
const configuredTimeout = Number(import.meta.env.VITE_API_TIMEOUT_MS);
const REQUEST_TIMEOUT_MS = Number.isFinite(configuredTimeout) && configuredTimeout > 0
? configuredTimeout : 120_000;
const METADATA_TIMEOUT_MS = Math.min(REQUEST_TIMEOUT_MS, 15_000);
/** Bound both the connection and body read; never automatically replay writes. */
async function performRequest<T>(
path: string,
options: RequestInit,
read: (response: Response) => Promise<T>,
timeoutMs = REQUEST_TIMEOUT_MS,
): Promise<T> {
const controller = new AbortController();
let timedOut = false;
const timer = setTimeout(() => {
timedOut = true;
controller.abort();
}, timeoutMs);
const abort = () => controller.abort(options.signal?.reason);
if (options.signal?.aborted) abort();
else options.signal?.addEventListener("abort", abort, { once: true });
try {
const response = await fetch(`${BASE}${path}`, { ...options, signal: controller.signal });
if (!response.ok) throw await errorFromResponse(response);
return await read(response);
} catch (error) {
if (timedOut) {
const mutation = options.method && !["GET", "HEAD"].includes(options.method.toUpperCase());
throw new ApiError(i18n.t(mutation ? "connection.requestTimeoutMutation" : "connection.requestTimeout"), 0, "request_timeout");
}
if (options.signal?.aborted || error instanceof ApiError) throw error;
if (error instanceof TypeError) {
throw new ApiError(i18n.t("connection.requestFailed"), 0, "network_error");
}
throw error;
} finally {
clearTimeout(timer);
options.signal?.removeEventListener("abort", abort);
}
}
export async function downloadGeneratedReport(reportId: string, filename: string): Promise<void> {
const blob = await performRequest(`/api/reports/${encodeURIComponent(reportId)}`, { headers: authHeaders() }, (response) => response.blob());
const url = URL.createObjectURL(blob);
const link = document.createElement("a");
link.href = url;
link.download = filename;
link.click();
setTimeout(() => URL.revokeObjectURL(url), 1000);
}
export class ApiError extends Error {
status: number;
code?: string;
constructor(message: string, status: number, code?: string) {
super(message);
this.name = "ApiError";
this.status = status;
this.code = code;
}
}
const AUTH_REQUIRED_MESSAGE_KEY = "agent.authRequired";
function getAuthRequiredMessage(): string {
return i18n.t(AUTH_REQUIRED_MESSAGE_KEY as never);
}
// Keep the existing string export compatible with consumers while updating its
// live ES-module binding whenever the active locale changes.
export let AUTH_REQUIRED_MESSAGE = getAuthRequiredMessage();
i18n.on("languageChanged", () => {
AUTH_REQUIRED_MESSAGE = getAuthRequiredMessage();
});
export function isAuthRequiredError(error: unknown): boolean {
return error instanceof ApiError && (error.status === 401 || error.status === 403);
}
export interface CorrelationResponse {
labels: string[];
// Undefined pairs (zero-variance leg — halted series, pegged stablecoin,
// fresh listing) come back as null: missing evidence, not 0.0. Mirrors the
// regime endpoint's (number | null)[] density convention.
matrix: (number | null)[][];
}
export interface CorrelationAnalysisResponse {
correlation: CorrelationResponse | null;
regime: CorrelationRegimeResponse | null;
errors: { correlation?: string; regime?: string };
coverage: { requested: string[]; missing: string[]; observations: number; first_date: string | null; last_date: string | null;
diagnostics: Record<string, { symbol: string; market: string; source: string | null; attempts: Array<{ source: string; reason: "source_unavailable" | "fetch_failed" | "no_data" }> }> };
}
export interface RegimeEpisode {
start: string;
end: string | null;
}
export interface CorrelationRegimeResponse {
labels: string[];
dates: string[];
density: (number | null)[];
smoothed: (number | null)[];
fused: number[];
episodes: RegimeEpisode[];
params: {
days: number;
corr_window: number;
edge_threshold: number;
smooth_window: number;
enter_threshold: number;
exit_threshold: number;
};
}
export interface PortfolioPosition {
portfolio_id?: string;
portfolio_name?: string;
source_mtime?: string;
instrument_id_kind?: string;
source_id?: string;
profile_id?: string;
source_label?: string;
broker: string;
symbol: string;
name: string;
asset_type: string;
market: string;
currency: string;
quantity: number;
cost_price?: number | null;
market_price?: number | null;
market_value_usd: number;
market_value_cny: number;
unrealized_pnl_usd?: number | null;
priced: boolean;
updated_at: string;
pricing_basis?: string;
price_as_of?: string;
price_error?: string;
}
export interface PortfolioConnectorCompatibility {
level: "native" | "contract_tested" | "experimental";
contract_version: number;
asset_scope: string;
note: string;
}
/**
* One portfolio source as of the last refresh.
*
* A source that could not be read has `status === "error"`, no totals, and
* contributes nothing to the snapshot totals; `last_success_at` (when present)
* is the timestamp of the last read that did succeed, and is only ever shown
* as history — never as a current valuation.
*/
export interface PortfolioAccount {
balance_details?: {
currency: string | null;
max_finance_amount: number | null;
remaining_finance_amount: number | null;
cash_infos: {
currency: string | null;
available_cash: number | null;
withdraw_cash: number | null;
frozen_cash: number | null;
settling_cash: number | null;
}[];
}[];
source_kind?: "connection" | "extraetf";
import_metadata?: { source_mtime: string; expires_at: string; as_of_source: string } | null;
source_id?: string;
profile_id?: string;
label?: string;
broker: string;
status: "ok" | "error";
last_success_at?: string;
total_usd?: number | null;
total_cny?: number | null;
total_display?: number | null;
priced_value_usd?: number;
cash_usd?: number;
unpriced_or_other_usd?: number;
position_count?: number;
priced_position_count?: number;
unpriced_position_count?: number;
error_code?: string;
error?: string;
failure_kind?: "authorization" | "transient";
reconnect_required?: boolean;
auth?: {
method: string;
renewal: "automatic" | "session" | "provider_managed";
readonly: boolean;
detail: string;
};
portfolio_compatibility?: PortfolioConnectorCompatibility;
}
export interface PortfolioSnapshot {
snapshot_id: string;
created_at: string;
/** False whenever any enabled source did not reach `status === "ok"`. */
complete: boolean;
display_currency?: string;
totals: { usd: number; cny: number; display?: number };
valuation?: {
priced_usd: number;
cash_usd: number;
unpriced_or_other_usd: number;
identified_coverage: number;
};
fx: { as_of?: string | null; source?: string; usd_cny: number; usd_hkd: number; rates?: Record<string, number>; fetched_at: string; stale: boolean };
accounts: PortfolioAccount[];
positions: PortfolioPosition[];
combined_holdings?: Array<{
canonical_id?: string;
symbol: string;
market_value_usd: number;
asset_type?: string;
brokers?: string[];
unrealized_pnl_usd?: number;
}>;
/** Backend-authored English notes; rendered verbatim, not translated. */
warnings: string[];
}
export interface PortfolioHistoryPoint {
total_eur?: string | null;
id: string;
created_at: string;
complete: number;
total_usd: string;
total_cny: string;
/** Historical HKD value at this snapshot’s FX rate; absent means unavailable. */
total_hkd?: string | null;
}
export interface RebalanceProposal {
mode: "proposal_only";
snapshot_id: string;
currency: string;
rows: Array<{ canonical_id: string; current_value: number; target_value: number; change_value: number }>;
}
export interface PortfolioRefreshState {
running: boolean;
current: string | null;
sources?: Record<string, { status: "idle" | "pending" | "refreshing" | "ok" | "error"; error?: string | null }>;
brokers?: Record<string, { status: "idle" | "pending" | "refreshing" | "ok" | "error"; error?: string | null }>;
}
export interface PortfolioReconnectState {
running: boolean;
source_id: string | null;
status: "idle" | "authorizing" | "authorized" | "error" | "timeout";
error: string | null;
started_at: string | null;
finished_at: string | null;
}
export interface PortfolioSourceSettings {
source_kind?: "connection" | "extraetf";
connection_id: string;
label: string;
enabled: boolean;
order: number;
include_cash: boolean;
}
export interface PortfolioSettings {
display_currency: string;
sources: PortfolioSourceSettings[];
}
export interface PortfolioSourceCatalogItem {
source_kind?: "connection" | "extraetf";
id: string;
connection_id: string;
profile_id: string;
connector: string;
label: string;
environment: "paper" | "live" | "import";
transport: "local_tws" | "remote_mcp" | "broker_sdk" | "local_plugin" | "file_import";
capabilities: string[];
readonly: boolean;
notes: string;
selected: boolean;
source_id?: string | null;
supports_reconnect: boolean;
credential_fields: CredentialField[];
credential_status: Record<string, boolean>;
credentials_configured: boolean;
portfolio_compatibility: PortfolioConnectorCompatibility | null;
}
export interface CredentialField {
name: string;
label: string;
secret: boolean;
required: boolean;
}
export interface ConnectorOnboarding {
schema_version: number;
auth_type: string;
credential_fields: CredentialField[];
dependency: string | null;
install_command: string | null;
test_operation: string;
setup_hint: string;
secret_storage: "os_keyring" | null;
}
export interface SocketEndpoint {
host: string;
port: number;
}
export interface LocalConnection {
portfolio_eligible?: boolean;
id: string;
profile_id: string;
label: string;
/** Broker account the reads are scoped to; empty until the user selects one. */
account_ref: string;
/** True when this connection reads nothing until an account is selected. */
account_selection_required: boolean;
endpoint?: SocketEndpoint | null;
effective_endpoint?: SocketEndpoint;
endpoint_error?: string;
connector: string;
environment: "paper" | "live";
transport: "local_tws" | "remote_mcp" | "broker_sdk" | "local_plugin";
readonly: boolean;
capabilities: string[];
supports_reconnect: boolean;
credential_fields: CredentialField[];
credential_status: Record<string, boolean>;
credentials_configured: boolean;
onboarding?: ConnectorOnboarding;
portfolio_compatibility: PortfolioConnectorCompatibility;
}
export interface ReadonlyConnectionProfile {
portfolio_eligible?: boolean;
id: string;
connector: string;
label: string;
environment: "paper" | "live";
transport: "local_tws" | "remote_mcp" | "broker_sdk" | "local_plugin";
capabilities: string[];
readonly: boolean;
notes: string;
local_plugin: boolean;
credential_fields: CredentialField[];
onboarding?: ConnectorOnboarding;
supports_reconnect: boolean;
account_selection_required: boolean;
portfolio_compatibility: PortfolioConnectorCompatibility;
invalid_plugin?: boolean;
directory?: string;
error?: string;
}
/** One account a broker login can reach, as the backend maps it for a picker. */
export interface BrokerAccountChoice {
account_ref: string;
label: string;
is_default: boolean;
agentic_allowed: boolean;
deactivated: boolean;
}
export interface ConnectionsResponse {
status: string;
connections: LocalConnection[];
profiles: ReadonlyConnectionProfile[];
plugin_directory: string;
}
export interface PortfolioSettingsResponse {
status: string;
settings: PortfolioSettings;
catalog: PortfolioSourceCatalogItem[];
}
async function errorFromResponse(res: Response): Promise<ApiError> {
let detail = `HTTP ${res.status}`;
let code: string | undefined;
try {
const body = await res.json();
// Options endpoints report errors under an `error` key
// ({status:"error", error} / {ok:false, error}) rather than detail/message.
const raw = body.detail ?? body.message ?? body.error;
if (typeof raw === "string" && raw) {
detail = raw;
} else if (raw && typeof raw === "object") {
const structured = raw as { code?: unknown; message?: unknown; max_length?: unknown };
if (typeof structured.code === "string" && structured.code) code = structured.code;
if (typeof structured.message === "string" && structured.message) detail = structured.message;
else if (code) detail = code;
if (code === "message_too_long" && typeof structured.max_length === "number") {
detail = i18n.t("agent.messageTooLong", { limit: structured.max_length.toLocaleString() });
}
}
} catch {
if (res.status >= 500) detail = i18n.t("connection.requestFailed");
}
if (res.status === 401 || res.status === 403) {
detail = getAuthRequiredMessage();
}
return new ApiError(detail, res.status, code);
}
export async function request<T>(path: string, options?: RequestInit, timeoutMs?: number): Promise<T> {
const { headers, ...rest } = options ?? {};
const mergedHeaders: Record<string, string> = { "Content-Type": "application/json", ...authHeaders() };
if (headers) {
new Headers(headers).forEach((value, key) => {
mergedHeaders[key] = value;
});
}
return performRequest(path, {
...rest,
headers: mergedHeaders,
}, async (res) => {
const text = await res.text();
if (!text) return {} as T;
const contentType = res.headers.get("content-type") || "";
if (!contentType.includes("application/json")) {
const preview = text.slice(0, 80).replace(/\s+/g, " ");
throw new ApiError(
`Expected JSON from ${path}, got ${contentType || "unknown content type"}: ${preview}`,
res.status,
);
}
return JSON.parse(text) as T;
}, timeoutMs);
}
export interface UploadResult {
status: string;
file_path: string;
filename: string;
}
async function uploadFile(file: File): Promise<UploadResult> {
const form = new FormData();
form.append("file", file);
return performRequest("/upload", { method: "POST", headers: authHeaders(), body: form }, (res) => res.json());
}
function appendQueryParam(url: string, key: string, value: string): string {
const sep = url.includes("?") ? "&" : "?";
return `${url}${sep}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
}
export interface ResearchArtifactRevision {
revision_id: string;
artifact_id: string;
revision_number: number;
previous_revision_id: string | null;
subject: string;
universe: string;
content: string;
content_hash: string;
provenance_hash: string;
identity_hash: string;
data_as_of: string;
created_at: string;
evidence: Array<Record<string, unknown>>;
evidence_missing: boolean;
verification_status: string;
completeness: string;
hypothesis_id: string | null;
goal_id: string | null;
session_id: string | null;
run_id: string | null;
}
export interface ResearchArtifactSaveResult {
revision: ResearchArtifactRevision;
created: boolean;
}
export interface SaveResearchArtifactRequest {
artifact_id?: string;
subject?: string;
universe?: string;
content: string;
data_as_of: string;
evidence?: Array<Record<string, unknown>>;
verification_status?: string;
completeness?: string;
hypothesis_id?: string;
goal_id?: string;
session_id?: string;
run_id?: string;
}
export const api = {
getPixelOffice: () => request<OfficeSnapshot>("/api/pixel-office"),
updatePixelOffice: (action: "create" | "assign" | "complete" | "rank", arguments_: Record<string, unknown>) =>
request<OfficeSnapshot>("/api/pixel-office/actions", { method: "POST", body: JSON.stringify({ action, arguments: arguments_ }) }),
uploadFile,
searchResearchArtifacts: (params: { query?: string; subject?: string; universe?: string; hypothesis_id?: string; goal_id?: string; session_id?: string; run_id?: string; limit?: number } = {}) => {
const search = new URLSearchParams();
Object.entries(params).forEach(([key, value]) => {
if (value !== undefined && value !== "") search.set(key, String(value));
});
const suffix = search.toString();
return request<{ count: number; artifacts: ResearchArtifactRevision[] }>(`/api/research-artifacts${suffix ? `?${suffix}` : ""}`);
},
getResearchArtifact: (artifactId: string) =>
request<{ artifact: ResearchArtifactRevision; revisions: ResearchArtifactRevision[] }>(`/api/research-artifacts/${encodeURIComponent(artifactId)}`),
getResearchRevision: (revisionId: string) =>
request<{ revision: ResearchArtifactRevision }>(`/api/research-artifacts/revision/${encodeURIComponent(revisionId)}`),
saveResearchArtifact: (body: SaveResearchArtifactRequest) =>
request<ResearchArtifactSaveResult>("/api/research-artifacts", { method: "POST", body: JSON.stringify(body) }),
getCorrelationAnalysis: (codes: string, days: number, method: "pearson" | "spearman", includeRegime: boolean, signal?: AbortSignal) =>
request<CorrelationAnalysisResponse>(`/correlation/analysis?${new URLSearchParams({ codes, days: String(days), method, include_regime: String(includeRegime) })}`, { signal }),
getCorrelation: (codes: string, days: number, method: "pearson" | "spearman") =>
request<CorrelationResponse>(
`/correlation?codes=${encodeURIComponent(codes)}&days=${encodeURIComponent(String(days))}&method=${encodeURIComponent(method)}`,
),
getCorrelationRegime: (codes: string, days: number) =>
request<CorrelationRegimeResponse>(
`/correlation/regime?codes=${encodeURIComponent(codes)}&days=${encodeURIComponent(String(days))}`,
),
getPortfolio: () => request<{ status: string; snapshot: PortfolioSnapshot | null }>("/api/portfolio"),
getPortfolioAnalysisContext: (snapshotId: string) =>
request<{ status: string; context: Record<string, unknown> }>(`/api/portfolio/analysis-context?snapshot_id=${encodeURIComponent(snapshotId)}`),
refreshPortfolio: () => request<{ status: string; snapshot: PortfolioSnapshot }>("/api/portfolio/refresh", { method: "POST" }),
getPortfolioRefreshStatus: () => request<{ status: string; refresh: PortfolioRefreshState }>("/api/portfolio/refresh-status"),
reconnectPortfolioSource: (sourceId: string) =>
request<{ status: string; reconnect: PortfolioReconnectState }>(`/api/portfolio/sources/${encodeURIComponent(sourceId)}/reconnect`, { method: "POST" }),
getPortfolioReconnectStatus: () =>
request<{ status: string; reconnect: PortfolioReconnectState }>("/api/portfolio/reconnect-status"),
getPortfolioSettings: () => request<PortfolioSettingsResponse>("/api/portfolio/settings"),
updatePortfolioSettings: (settings: PortfolioSettings) =>
request<PortfolioSettingsResponse>("/api/portfolio/settings", {
method: "PUT",
body: JSON.stringify(settings),
}),
getConnections: () => request<ConnectionsResponse>("/api/connections"),
createConnection: (payload: { id: string; profile_id: string; label: string }) =>
request<{ status: string; connection: LocalConnection }>("/api/connections", {
method: "POST",
body: JSON.stringify(payload),
}),
saveConnectionCredentials: (connectionId: string, values: Record<string, string>) =>
request<{ status: string; credential_status: Record<string, boolean> }>(
`/api/connections/${encodeURIComponent(connectionId)}/credentials`,
{ method: "POST", body: JSON.stringify({ values }) },
),
saveConnectionEndpoint: (connectionId: string, endpoint: SocketEndpoint) =>
request<{ status: string }>(
`/api/connections/${encodeURIComponent(connectionId)}/endpoint`,
{ method: "PUT", body: JSON.stringify(endpoint) },
),
checkConnection: (connectionId: string) =>
request<{ status: string; connection_id: string; report: Record<string, unknown> }>(
`/api/connections/${encodeURIComponent(connectionId)}/check`,
{ method: "POST" },
),
getConnectionAccounts: (connectionId: string) =>
request<{ status: string; connection_id: string; account_ref: string; accounts: BrokerAccountChoice[] }>(
`/api/connections/${encodeURIComponent(connectionId)}/accounts`,
),
selectConnectionAccount: (connectionId: string, accountRef: string) =>
request<{ status: string; connection: LocalConnection }>(
`/api/connections/${encodeURIComponent(connectionId)}/account`,
{ method: "PUT", body: JSON.stringify({ account_ref: accountRef }) },
),
deleteConnection: (connectionId: string) =>
request<{ status: string; deleted: string }>(
`/api/connections/${encodeURIComponent(connectionId)}`,
{ method: "DELETE" },
),
importExtraEtf: (payload: { csv_text: string; label: string; source_mtime: string; expected_positions: number; max_age_days: number }) =>
request<{ status: string; import: { id: string } }>("/api/portfolio/imports/extraetf", { method: "POST", body: JSON.stringify(payload) }),
proposePortfolioRebalance: (snapshotId: string, targetWeights: Record<string, number>) =>
request<{ status: string; proposal: RebalanceProposal }>("/api/portfolio/rebalance", { method: "POST", body: JSON.stringify({ snapshot_id: snapshotId, target_weights: targetWeights }) }),
getPortfolioHistory: (limit = 180) =>
request<{ status: string; history: PortfolioHistoryPoint[] }>(`/api/portfolio/history?limit=${encodeURIComponent(String(limit))}`),
downloadPortfolioCsv: async () => {
return performRequest("/api/portfolio/export.csv", { headers: authHeaders() }, (response) => response.blob());
},
listRuns: (limit?: number) => request<RunListItem[]>(`/runs${limit ? `?limit=${encodeURIComponent(String(limit))}` : ""}`),
getRun: (id: string, params: RunDetailParams = {}) => {
const q = new URLSearchParams();
if (params.chart_payload) q.set("chart_payload", params.chart_payload);
if (params.chart_symbol) q.set("chart_symbol", params.chart_symbol);
const qs = q.toString();
return request<RunData>(`/runs/${id}${qs ? `?${qs}` : ""}`);
},
getRunPreview: (id: string) => request<RunPreview>(`/runs/${id}/preview`),
getRunCode: (id: string) => request<Record<string, string>>(`/runs/${id}/code`),
getRunFactor: (id: string) => request<FactorReportPayload>(`/runs/${id}/factor`),
getRunAttribution: (id: string) => request<AttributionResponse>(`/runs/${encodeURIComponent(id)}/attribution`),
getRunPine: (id: string) => request<PineScriptResult>(`/runs/${id}/pine`),
listSessions: () => request<SessionItem[]>("/sessions", undefined, METADATA_TIMEOUT_MS),
createSession: (title?: string) => request<SessionItem>("/sessions", { method: "POST", body: JSON.stringify({ title: title || "" }) }),
deleteSession: (sid: string) => request<{ status: string }>(`/sessions/${sid}`, { method: "DELETE" }),
renameSession: (sid: string, title: string) => request<{ status: string }>(`/sessions/${sid}`, { method: "PATCH", body: JSON.stringify({ title }) }),
// Codex-style LLM summary title from the first exchange; backend refuses to
// overwrite a manual rename, so this is safe to fire-and-forget.
autoTitleSession: (sid: string) => request<{ status: string; title: string }>(`/sessions/${sid}/title/auto`, { method: "POST" }),
// Scheduled research: cadence + timezone are stored as authored (local
// wall-clock cron + IANA key), so list rows render without any UTC math.
listScheduledRuns: (signal?: AbortSignal) => request<ScheduledRun[]>("/scheduled-runs", { signal }),
createScheduledRun: (body: CreateScheduledRunRequest) =>
request<ScheduledRun>("/scheduled-runs", { method: "POST", body: JSON.stringify(body) }),
updateScheduledRun: (id: string, body: UpdateScheduledRunRequest) =>
request<ScheduledRun>(`/scheduled-runs/${encodeURIComponent(id)}`, {
method: "PATCH",
body: JSON.stringify(body),
}),
deleteScheduledRun: (id: string) =>
request<void>(`/scheduled-runs/${encodeURIComponent(id)}`, { method: "DELETE" }),
commitScheduledResearchProposal: (proposalId: string) =>
request<ScheduledResearchProposal>(
`/scheduled-runs/proposals/${encodeURIComponent(proposalId)}/commit`,
{ method: "POST" },
),
discardScheduledResearchProposal: (proposalId: string) =>
request<ScheduledResearchProposal>(
`/scheduled-runs/proposals/${encodeURIComponent(proposalId)}/discard`,
{ method: "POST" },
),
sendMessage: (sid: string, content: string) => request<{ message_id: string; attempt_id: string }>(`/sessions/${sid}/messages`, { method: "POST", body: JSON.stringify({ content }) }),
cancelSession: (sid: string) => request<{ status: string }>(`/sessions/${sid}/cancel`, { method: "POST" }),
getSessionMessages: (sid: string) => request<MessageItem[]>(`/sessions/${sid}/messages`),
createGoal: (sid: string, body: CreateGoalRequest) =>
request<GoalSnapshot>(`/sessions/${sid}/goal`, {
method: "POST",
body: JSON.stringify(body),
}),
getGoal: (sid: string) => request<GoalSnapshot>(`/sessions/${sid}/goal`),
updateGoal: (sid: string, body: UpdateGoalRequest) =>
request<UpdateGoalResponse>(`/sessions/${sid}/goal`, {
method: "PATCH",
body: JSON.stringify(body),
}),
addGoalEvidence: (sid: string, body: AddGoalEvidenceRequest) =>
request<AddGoalEvidenceResponse>(`/sessions/${sid}/goal/evidence`, {
method: "POST",
body: JSON.stringify(body),
}),
updateGoalStatus: (sid: string, body: UpdateGoalStatusRequest) =>
request<UpdateGoalStatusResponse>(`/sessions/${sid}/goal/status`, {
method: "PATCH",
body: JSON.stringify(body),
}),
// Returns the bare stream URL (no auth in the query string). The SSE ticket
// is minted per connect/reconnect inside useSSE (tickets are single-use, so
// baking one into a cached URL would break reconnection).
sseUrl: (sid: string, options?: { replay?: "active" }) => {
let url = `${BASE}/sessions/${sid}/events`;
if (options?.replay) url = appendQueryParam(url, "replay", options.replay);
return url;
},
// Swarm API
listSwarmPresets: () => request<SwarmPreset[]>("/swarm/presets"),
createSwarmRun: (preset_name: string, user_vars: Record<string, string>) =>
request<{ id: string; status: string }>("/swarm/runs", {
method: "POST",
body: JSON.stringify({ preset_name, user_vars }),
}),
listSwarmRuns: () => request<SwarmRunSummary[]>("/swarm/runs"),
getSwarmRun: (id: string) => request<Record<string, unknown>>(`/swarm/runs/${id}`),
swarmSseUrl: (id: string) => withAuthTicket(`${BASE}/swarm/runs/${id}/events`),
cancelSwarmRun: (id: string) =>
request<{ status: string }>(`/swarm/runs/${id}/cancel`, { method: "POST" }),
retrySwarmRun: (id: string) =>
request<{ id: string; status: string; preset_name: string }>(`/swarm/runs/${id}/retry`, { method: "POST" }),
getLLMSettings: () => request<LLMSettings>("/settings/llm"),
updateLLMSettings: (settings: UpdateLLMSettingsRequest) =>
request<LLMSettings>("/settings/llm", {
method: "PUT",
body: JSON.stringify(settings),
}),
listLLMModels: (settings: ListLLMModelsRequest) =>
request<LLMModelsResponse>("/settings/llm/models", {
method: "POST",
body: JSON.stringify(settings),
}),
listCustomProviders: () =>
request<{ status: string; providers: CustomProviderProfile[] }>("/settings/custom-providers"),
testCustomProvider: (settings: { base_url: string; model: string; api_key: string }) =>
request<CustomProviderTestResponse>("/settings/custom-providers/test", {
method: "POST",
body: JSON.stringify(settings),
}),
saveCustomProvider: (settings: CustomProviderSaveRequest) =>
request<{ status: string; provider: CustomProviderProfile }>("/settings/custom-providers", {
method: "POST",
body: JSON.stringify(settings),
}),
activateCustomProvider: (profileId: string) =>
request<{ status: string; active_id: string; model: string; base_url: string }>(
`/settings/custom-providers/${encodeURIComponent(profileId)}/activate`, {
method: "POST",
body: JSON.stringify({ confirm: true }),
},
),
getDataSourceSettings: () => request<DataSourceSettings>("/settings/data-sources"),
updateDataSourceSettings: (settings: UpdateDataSourceSettingsRequest) =>
request<DataSourceSettings>("/settings/data-sources", {
method: "PUT",
body: JSON.stringify(settings),
}),
getChannelStatus: () => request<ChannelRuntimeStatus>("/channels/status"),
startChannels: () => request<ChannelRuntimeActionResponse>("/channels/start", { method: "POST" }),
stopChannels: () => request<ChannelRuntimeActionResponse>("/channels/stop", { method: "POST" }),
runChannelPairingCommand: (body: ChannelPairingCommandRequest) =>
request<ChannelPairingCommandResponse>("/channels/pairing/command", {
method: "POST",
body: JSON.stringify(body),
}),
// Web-based IM channel configuration; non-2xx (400/422) throws ApiError.
getChannelsConfig: () => request<ChannelsConfigResponse>("/channels/config"),
putChannelConfig: (name: string, body: ChannelPutBody) =>
request<ChannelPutResult>(`/channels/config/${encodeURIComponent(name)}`, {
method: "PUT",
body: JSON.stringify(body),
}),
testChannel: (name: string, body?: ChannelTestBody) =>
request<ChannelTestResult>(`/channels/${encodeURIComponent(name)}/test`, {
method: "POST",
body: JSON.stringify(body ?? {}),
}),
// Alpha Zoo API
getAlphaReadiness: () => request<AlphaReadiness>("/alpha/readiness", {}, METADATA_TIMEOUT_MS),
getAlphaBenchJob: (jobId: string) => request<AlphaJobSnapshot<AlphaBenchResult>>(`/alpha/bench/${encodeURIComponent(jobId)}`, {}, METADATA_TIMEOUT_MS),
getAlphaCompareJob: (jobId: string) => request<AlphaJobSnapshot<AlphaCompareResult>>(`/alpha/compare/${encodeURIComponent(jobId)}`, {}, METADATA_TIMEOUT_MS),
listAlphas: (params: AlphaListParams = {}) => {
const q = new URLSearchParams();
if (params.zoo) q.set("zoo", params.zoo);
if (params.theme) q.set("theme", params.theme);
if (params.universe) q.set("universe", params.universe);
if (params.limit !== undefined) q.set("limit", String(params.limit));
const qs = q.toString();
return request<AlphaListResponse>(`/alpha/list${qs ? `?${qs}` : ""}`);
},
getAlpha: (alphaId: string) =>
request<AlphaDetailResponse>(`/alpha/${encodeURIComponent(alphaId)}`),
createAlphaBench: (body: AlphaBenchRequest) =>
request<{ status: string; job_id: string }>("/alpha/bench", {
method: "POST",
body: JSON.stringify(body),
}),
alphaBenchStreamUrl: (jobId: string) =>
withAuthTicket(`${BASE}/alpha/bench/${encodeURIComponent(jobId)}/stream`),
createAlphaCompare: (body: AlphaCompareRequest) =>
request<{ status: string; job_id: string }>("/alpha/compare", {
method: "POST",
body: JSON.stringify(body),
}),
alphaCompareStreamUrl: (jobId: string) =>
withAuthTicket(`${BASE}/alpha/compare/${encodeURIComponent(jobId)}/stream`),
// Options Lab
analyzeOptionsPayoff: (body: OptionsPayoffRequest, signal?: AbortSignal) =>
request<OptionsPayoffResponse>("/options/payoff", {
method: "POST",
body: JSON.stringify(body),
signal,
}),
getOptionsChain: (ticker: string, expiration?: number) => {
const q = new URLSearchParams();
q.set("ticker", ticker);
if (expiration !== undefined) q.set("expiration", String(expiration));
return request<OptionsChainResponse>(`/options/chain?${q.toString()}`);
},
// Connector runtime channel — privileged surface actions (NOT agent tools).
// commit is the ONLY action that writes a mandate; halt trips the kill switch.
getLiveAccounts: (broker: string) =>
request<{ status: string; broker: string; account_selection_required: boolean; accounts: BrokerAccountChoice[] }>(
`/live/accounts?broker=${encodeURIComponent(broker)}`,
),
commitMandate: (body: CommitMandateRequest) =>
request<CommitMandateResponse>("/mandate/commit", {
method: "POST",
body: JSON.stringify(body),
}),
haltLive: (session_id?: string, broker?: string, reason?: string) =>
request<HaltLiveResponse>("/live/halt", {
method: "POST",
body: JSON.stringify({ session_id, broker, reason }),
}),
resumeLive: (session_id?: string, broker?: string) =>
request<HaltLiveResponse>("/live/resume", {
method: "POST",
body: JSON.stringify({ session_id, broker }),
}),
// Read the persistent runtime status across all authorized brokers (SPEC §7.5).
// Polled by the RunnerStatus panel; a plain authenticated GET, never a chat message.
getLiveStatus: (signal?: AbortSignal) => request<LiveStatus>("/live/status", { signal }),
verifyConnector: (profileId: string) =>
request<ConnectorVerifyResponse>(`/live/connectors/${encodeURIComponent(profileId)}/verify?force=true`, {
method: "POST",
}),
authorizeLive: (broker: string) =>
request<LiveAuthorizeResponse>("/live/authorize", {
method: "POST",
body: JSON.stringify({ broker }),
}),
// Start/stop the persistent runner (SPEC §7.5). Privileged surface actions, not agent tools.
startLiveRunner: (broker: string) =>
request<LiveRunnerResponse>("/live/runner/start", {
method: "POST",
body: JSON.stringify({ broker }),
}),
saveRunnerSettings: (broker: string, settings: LiveDecisionSettings) =>
request<LiveDecisionBudget>(`/live/runner/settings?broker=${encodeURIComponent(broker)}`, {
method: "PUT",
body: JSON.stringify(settings),
}),
stopLiveRunner: (broker: string) =>
request<LiveRunnerResponse>("/live/runner/stop", {
method: "POST",
body: JSON.stringify({ broker }),
}),
};
// --- Scheduled research types ---
export interface VerdictItem {
symbol: string;
state: string;
reason: string;
}
export interface VerdictRecord {
session_id: string;
recorded_at: number;
parse: string;
outcome: string;
items: VerdictItem[];
previous: VerdictRecord | null;
}
export interface ScheduledRun {
id: string;
prompt: string;
title: string;
source_type: "prompt" | "playbook" | "system";
playbook_slug: string | null;
end_at: number | null;
schedule: string;
next_run_at: number;
status: string;
created_at: number;
last_run_at: number | null;
consecutive_failures: number;
last_error: string | null;
failure_kind: string | null;
config: Record<string, unknown>;
timezone: string | null;
// Delivery is opt-in per monitor: a null channel means results stay in the
// app, which is what every monitor created before this did.
delivery_channel: string | null;
delivery_target: string | null;
delivery_format: "html" | "pdf" | null;
protect_pdf: boolean;
delivery_target_ref: string | null;
delivery_target_label: string | null;
delivery_status: string;
delivery_error: string | null;
delivery_updated_at: number | null;
delivery_attempts: number;
delivery_provider_message_id: string | null;
// The latest run's parsed verdict, embedded with its predecessor so the list
// renders a delta in one query. Null until a completed run records one.
last_verdict: VerdictRecord | null;
}
export interface CreateScheduledRunRequest {
id?: string;
title?: string | null;
prompt: string;
schedule: string;
timezone?: string | null;
end_at?: number | null;
config?: Record<string, unknown>;
delivery_channel?: string | null;
delivery_target?: string | null;
delivery_format?: "html" | "pdf" | null;
protect_pdf?: boolean;
delivery_target_ref?: string | null;
}
export interface UpdateScheduledRunRequest {
title?: string | null;
prompt?: string;
schedule?: string;
timezone?: string | null;
end_at?: number | null;
config?: Record<string, unknown> | null;
delivery_channel?: string | null;
delivery_target?: string | null;
delivery_target_ref?: string | null;
delivery_format?: "html" | "pdf" | null;
protect_pdf?: boolean;
}
export interface ScheduledResearchProposalJob {
id: string;
title: string;
state: string;
source: { kind: string; playbook_slug?: string | null; prompt?: string | null };
schedule: {
expression: string;
timezone: string | null;
next_run_at: number | null;
end_at: number | null;
};
delivery: {
channel: string | null;
target_ref: string | null;
target_label: string | null;
format?: "html" | "pdf" | null;
protect_pdf?: boolean;
status: string;
};
}
export interface ScheduledResearchProposal {
type: "scheduled_research.proposal";
proposal_id: string;
operation: "create" | "cancel";
status: "pending" | "committed" | "discarded" | "expired";
expires_at: number;
job: ScheduledResearchProposalJob;
job_id?: string | null;
committed_job_id?: string | null;
}
// --- Swarm types ---
export interface SwarmPreset {
name: string;
title: string;
description: string;
agent_count: number;
variables: { name: string; description: string; required: boolean }[];
}
export interface SwarmRunSummary {
id: string;
preset_name: string;
status: string;
created_at: string;
task_count: number;
completed_count: number;
}
export interface LLMProviderOption {
name: string;
label: string;
api_key_env?: string | null;
base_url_env: string;
default_model: string;
default_base_url: string;
base_url_options?: string[];
api_key_required: boolean;
auth_type?: string;
login_command?: string | null;
/** Reasoning effort levels the provider accepts, besides "" (provider default). */
reasoning_efforts?: string[];
}
export interface LLMSettings {
provider: string;
model_name: string;
base_url: string;
api_key_env?: string | null;
api_key_configured: boolean;
api_key_hint?: string | null;
api_key_required: boolean;
temperature: number;
timeout_seconds: number;
max_retries: number;
reasoning_effort: string;
sse_timeout_seconds: number;
env_path: string;
providers: LLMProviderOption[];
}
export interface UpdateLLMSettingsRequest {
provider: string;
model_name: string;
base_url: string;
api_key?: string;
clear_api_key?: boolean;
temperature: number;
timeout_seconds: number;
max_retries: number;
reasoning_effort?: string;
}
export interface ListLLMModelsRequest {
provider: string;
base_url?: string;
api_key?: string;
refresh?: boolean;
}
export interface CustomProviderProfile {
id: string;
label: string;
base_url: string;
model: string;
api_key_configured: boolean;
active: boolean;
last_tested_at?: string | null;
}
export interface CustomProviderTestResponse {
status: "ok";
test_id: string;
response_preview: string;
latency_ms: number;
}
export interface CustomProviderSaveRequest {
id: string;
label: string;
base_url: string;
model: string;
api_key: string;
test_id: string;
}
export interface LLMModelsResponse {
provider: string;
models: string[];
source: "provider" | "default";
warning_code?:
| "oauth_discovery_unsupported"
| "api_key_required"
| "model_list_unavailable"
| null;
/** Model id -> reasoning effort levels it accepts; empty means none. */
effort_levels?: Record<string, string[]> | null;
model_labels?: Record<string, string> | null;
default_effort_levels?: Record<string, string> | null;
}
export interface SourceOrderEntry {
market: string;
env_var: string;
default_order: string[];
effective_order: string[];
override?: string[] | null;
override_invalid: boolean;
}
export interface SourceOrderUpdate {
market: string;
/** New order (permutation of default_order). null/omitted = reset to default. */
order?: string[] | null;
}
export const gildataFeatures = [
"fin_query",
"stock_selection",
"symbol_search",
"shannon",
"market_quotes",
"fund_nav",
"macro_series",
"announcements",
"broker_reports",
] as const;
export type GildataFeature = typeof gildataFeatures[number];
export interface DataSourceSettings {
gildata_features?: GildataFeature[];
tushare_token_configured: boolean;
tushare_token_hint?: string | null;
gildata_token_configured: boolean;
gildata_token_hint?: string | null;
baostock_supported: boolean;
baostock_installed: boolean;
baostock_message: string;
env_path: string;
source_orders?: SourceOrderEntry[];
}
export interface UpdateDataSourceSettingsRequest {
gildata_features?: GildataFeature[];
tushare_token?: string;
clear_tushare_token?: boolean;
gildata_token?: string;
clear_gildata_token?: boolean;
source_orders?: SourceOrderUpdate[];
}
export interface DeliveryTargetSuggestion {
target: string;
kind?: string;
label?: string;
}
export interface ChannelAdapterStatus {
name: string;
display_name: string;
configured: boolean;
enabled: boolean;
available: boolean;
loaded: boolean;
running: boolean;
error?: string;
install_hint?: string;
delivery_target_label?: string;
delivery_target_kind?: string;
delivery_target_placeholder?: string;
delivery_target_input_type?: string;
delivery_target_suggestions?: DeliveryTargetSuggestion[];
}
export interface ChannelRuntimeStatus {
running: boolean;
inbound_queue: number;
outbound_queue: number;
session_count: number;
channels: Record<string, ChannelAdapterStatus>;
}
export interface ChannelRuntimeActionResponse extends ChannelRuntimeStatus {
status: string;
}
export interface ChannelPairingCommandRequest {
channel: string;
command: string;
}
export interface ChannelPairingCommandResponse {
channel: string;
reply: string;
}
export interface ChannelFieldHint {
key: string;
type: "text" | "password" | "bool" | "list";
secret: boolean;
required: boolean;
help_key?: string | null;
/** Closed set of valid values; the panel renders a <select> when present. */
choices?: string[];
}
export interface ChannelSecretStatus {
set: boolean;
masked: string;
}
export interface ChannelConfigEntry {
display_name: string;
available: boolean;
loaded: boolean;
install_hint: string;
error: string;
supports_test: boolean;
sdk_available: boolean;
fields: ChannelFieldHint[];
values: Record<string, unknown>;
secrets: Record<string, ChannelSecretStatus>;
pdf_password_configured?: boolean;
}
export interface ChannelsConfigResponse {
/** Display-only path (home-relative `~/...` or a bare basename), never absolute. */
config_path: string;
writable: boolean;
runtime_running: boolean;
channels: Record<string, ChannelConfigEntry>;
}
// Merge-patches one channel section: an absent secret field is kept as-is,
// `clear_<field>: true` removes a stored secret, and an enable transition
// auto-verifies credentials unless `skip_verify` is set.
export type ChannelPutBody = {
config: Record<string, unknown>;
skip_verify?: boolean;
} & {
[clearFlag: `clear_${string}`]: boolean | undefined;
};
export interface ChannelPutResult {
channel: ChannelConfigEntry;
applied: "refreshed" | "hot_swapped" | "reset" | "deferred";
reset_reason?: string;
}
export type ChannelTestBody = {
config?: Record<string, unknown>;
} & {
[clearFlag: `clear_${string}`]: boolean | undefined;
};
export interface ChannelTestResult {
ok: boolean;
code: "ok" | "invalid_credentials" | "network" | "unsupported";
detail?: string;
sdk_available: boolean;
tested_saved_config: boolean;
}
// --- Types matching backend API contracts ---
export interface RunListItem {
run_id: string;
status: string;
created_at: string;
prompt?: string;
total_return?: number;
sharpe?: number;
codes?: string[];
start_date?: string;
end_date?: string;
}
export interface RunDetailParams {
chart_payload?: "summary";
chart_symbol?: string;
}
export interface PriceBar {
time: string;
timestamp?: string;
code?: string;
open: number;
high: number;
low: number;
close: number;
volume: number;
}
export interface TradeMarker {
time: string;
timestamp?: string;
code?: string;
side: "BUY" | "SELL";
price: number;
qty?: number;
reason?: string;
text?: string;
}
export interface EquityPoint {
time: string;
equity: string | number;
drawdown: string | number;
}
/** What a chat run card needs from `GET /runs/{id}/preview`. */
export interface RunPreview {
metrics: BacktestMetrics | null;
equity_curve: EquityPoint[];
/** False for plain chat replies, which own a run directory but no report. */
report_worthy: boolean;
}
/** Monte Carlo fan-chart payload: percentile envelope + sampled paths over trade order. */
export interface MonteCarloEquityPaths {
steps: number[];
initial_capital: number;
actual: number[];
band_p5: number[];
band_p25: number[];
band_p50: number[];
band_p75: number[];
band_p95: number[];
samples: number[][];
}
export interface ValidationData {
monte_carlo?: {
actual_sharpe: number;
actual_max_dd: number;
p_value_sharpe: number;
p_value_max_dd: number;
simulated_sharpe_mean: number;
simulated_sharpe_std: number;
simulated_sharpe_p5: number;
simulated_sharpe_p95: number;
n_simulations: number;
n_trades: number;
sharpe_samples?: number[];
equity_paths?: MonteCarloEquityPaths;
} | { error: string };
bootstrap?: {
observed_sharpe: number;
ci_lower: number;
ci_upper: number;
median_sharpe: number;
prob_positive: number;
confidence: number;
n_bootstrap: number;
sharpe_samples?: number[];
error?: string;
};
walk_forward?: {
n_windows: number;
windows: Array<{
window: number;
start: string;
end: string;
return: number;
sharpe: number;
max_dd: number;
trades: number;
win_rate: number;
}>;
profitable_windows: number;
consistency_rate: number;
return_mean: number;
return_std: number;
sharpe_mean: number;
sharpe_std: number;
error?: string;
};
}
export interface RiskXRayPayload {
inputs?: {
symbols?: string[];
weights?: Record<string, number>;
aligned_days?: number;
return_observations?: number;
first_date?: string;
last_date?: string;
};
concentration?: { hhi?: number; effective_n?: number; top_weight?: number };
volatility?: { annualized_vol?: number };
drawdown?: { max_drawdown?: number };
tail_risk?: Record<string, unknown>;
diversification?: Record<string, unknown>;
correlation?: Record<string, unknown>;
skipped?: string[];
warnings?: string[];
}
export interface RebalanceNotesPayload {
rebalances?: Array<{
date: string;
turnover: number;
entries?: Array<{ code: string; to: number }>;
exits?: Array<{ code: string; from: number }>;
top_moves?: Array<{ code: string; from: number; to: number; delta: number }>;
}>;
summary?: {
target_change_count: number;
/** Legacy key on runs produced before the #1275 execution-evidence fix. */
rebalance_count?: number;
turnover_total: number;
turnover_mean: number;
turnover_max: number;
largest_rebalance_date?: string | null;
rebalance_executed_bars?: number;
rebalance_executed_fills?: number;
rebalance_realized_turnover?: number;
};
}
export interface FactorIcStats {
ic_mean?: number | null;
ic_std?: number | null;
ir?: number | null;
ic_positive_ratio?: number | null;
ic_count?: number | null;
[key: string]: unknown;
}
export interface FactorResult {
name: string;
path: string;
ic_series: Array<{ date: string; ic: number }>;
ic_stats?: FactorIcStats;
group_equity: Array<{ date: string } & Record<string, number | string>>;
n_groups: number;
long_short_spread: number | null;
group_final_equity: Record<string, number>;
truncated?: {
ic_series?: boolean;
ic_stats?: boolean;
group_equity?: boolean;
};
}
export interface FactorReportPayload {
exists: boolean;
factors: FactorResult[];
ic_correlation: { labels: string[]; matrix: number[][] } | null;
}
// --- Attribution types (GET /runs/{runId}/attribution) ---
export interface AttributionBenchmarkInfo {
ticker: string | null;
mode: "auto_equal_weight" | "auto_market" | "explicit";
}
export interface AttributionRollingPoint {
date: string;
beta: number;
alpha_annualized: number;
}
export interface AttributionCumulativePoint {
date: string;
portfolio: number;
benchmark: number;
/** Portfolio-minus-benchmark cumulative return; plotted as the active line. */
active: number;
}
export interface AttributionFactor {
beta: number;
alpha_per_period: number;
alpha_annualized: number;
alpha_t_stat: number;
r_squared: number;
n_obs: number;
rolling_window: number;
rolling: AttributionRollingPoint[] | null;
cumulative: AttributionCumulativePoint[];
}
export interface AttributionSectorEntry {
sector: string;
portfolio_weight: number;
benchmark_weight: number;
portfolio_return: number;
benchmark_return: number;
allocation: number;
selection: number;
interaction: number;
total: number;
}
export interface AttributionBrinson {
mode: "symbol" | "asset_class" | "invested_cash";
portfolio_return: number;
benchmark_return: number;
active_return: number;
allocation: number;
selection: number;
interaction: number;
sectors: AttributionSectorEntry[];
}
export interface AttributionResponse {
exists: boolean;
benchmark: AttributionBenchmarkInfo | null;
factor: AttributionFactor | null;
brinson: AttributionBrinson | null;
notes: string[];
}
/**
* One provider-reported LLM usage event inside `llm_usage.per_iteration`.
* Field names mirror the on-disk artifact written by `agent/src/agent/llm_usage.py`.
* The two `cache_*` keys appear only once the provider reports a cache event for
* that call, so they are optional — never fabricated.
*/
export interface LlmUsageCall {
iter: number;
input_tokens: number;
output_tokens: number;
total_tokens: number;
cache_read_tokens?: number;
cache_creation_tokens?: number;
}
/**
* Run-scoped LLM usage summary returned by `GET /runs/{id}` (`RunResponse.llm_usage`,
* optional on the backend and `null`/absent when the run recorded no usage events).
*/
export interface LlmUsage {
provider: string;
model: string;
totals: {
input_tokens: number;
output_tokens: number;
total_tokens: number;
calls: number;
/** Present only after a provider cache event, like the per-iteration keys. */
cache_read_tokens?: number;
cache_creation_tokens?: number;
};
per_iteration: LlmUsageCall[];
updated_at: string;
}
export interface RunData {
status: string;
run_id: string;
prompt?: string;
elapsed_seconds?: number;
run_directory?: string;
run_stage?: string;
run_context?: Record<string, unknown>;
metrics?: BacktestMetrics;
artifacts?: ArtifactInfo[];
run_card?: RunCard;
/** Provider-reported AgentLoop usage summary; null/absent when the run recorded no usage events. */
llm_usage?: LlmUsage | null;
risk_xray?: RiskXRayPayload;
rebalance_notes?: RebalanceNotesPayload;
validation?: ValidationData;
has_factor_artifacts?: boolean;
chart_symbols?: string[];
price_series?: Record<string, PriceBar[]>;
indicator_series?: Record<string, Record<string, IndicatorPoint[]>>;
trade_markers?: TradeMarker[];
equity_curve?: EquityPoint[];
trade_log?: Array<Record<string, string>>;
/** Full equity.csv rows (timestamp/equity/drawdown as strings); not capped like equity_curve. */
artifacts_equity_csv?: Array<Record<string, string>>;
artifacts_metrics_csv?: Array<Record<string, string>>;
artifacts_trades_csv?: Array<Record<string, string>>;
/** Filled portfolio weights per date (rows: {timestamp, <symbol>: weight-string}). */
artifacts_positions_csv?: Array<Record<string, string>>;
/** Requested target weights per date, same row shape as artifacts_positions_csv. */
artifacts_target_positions_csv?: Array<Record<string, string>>;
run_logs?: Array<{ source?: string; line_number?: number; message?: string }>;
}
// --- Positions sector-map types (GET /runs/{runId}/positions/sectors) ---
/** Asset classes reported by the backend sector-map endpoint. */
export type SectorAssetClass =
| "a_share"
| "us_equity"
| "hk_equity"
| "india_equity"
| "kr_equity"
| "ca_equity"
| "ar_equity"
| "br_equity"
| "uk_equity"
| "vietnam_equity"
| "index"
| "crypto"
| "futures"
| "forex";
export interface SectorInfo {
asset_class: SectorAssetClass;
/** Resolved industry name, or null when unresolved / not applicable. */
industry: string | null;
/** Provenance of `industry` (e.g. "eastmoney"), null when unresolved. */
industry_source: string | null;
}
export interface SectorMapResponse {
ok: boolean;
run_id?: string;
resolved_at?: string;
cached?: boolean;
symbols: Record<string, SectorInfo>;
unresolved?: string[];
/** Total symbol columns in positions.csv (may exceed `symbol_limit`). */
total_symbols?: number;
/** Max symbols that receive a network industry lookup per resolve. */
symbol_limit?: number;
/** Present when the run has no positions artifact. */
note?: string;
}
/**
* Fetch the resolved sector map for one run's positions artifact.
* Uses the same auth-header + error-envelope conventions as every other
* fetcher in this module (via the shared `request` helper).
*/
export function fetchRunSectorMap(runId: string, refresh?: boolean): Promise<SectorMapResponse> {
const qs = refresh ? "?refresh=1" : "";
return request<SectorMapResponse>(`/runs/${encodeURIComponent(runId)}/positions/sectors${qs}`);
}
export interface RunCardToolTrace {
tool: "backtest" | "load_data" | "generate_signals";
started_at: string;
ended_at: string;
status: "ok" | "error" | "cancelled";
args_hash: string;
result_hash: string;
}
export interface RunCardCitation {
metric: string;
artifact_id: string;
column: string;
/** One-based data row, excluding the CSV header. */
row: number;
sha256: string;
}
export interface RunCard {
schema_version?: string;
generated_at?: string;
run_dir?: string;
backtest?: Record<string, unknown>;
reproducibility?: Record<string, unknown>;
data_sources?: string[];
metrics?: Record<string, unknown>;
// Carried alongside `metrics`, which is scalar-only: dict/list-shaped metrics
// (e.g. which sleeve a plan rejection dropped) reach the card here.
structured_metrics?: Record<string, unknown>;
validation?: unknown;
warnings?: string[];
artifacts?: RunCardArtifact[];
tool_traces?: RunCardToolTrace[];
citations?: RunCardCitation[];
[key: string]: unknown;
}
export interface RunCardArtifact {
path: string;
size_bytes: number;
sha256: string;
}
export interface BacktestMetrics {
final_value: number;
total_return: number;
annual_return: number;
max_drawdown: number;
sharpe: number;
win_rate: number;
trade_count: number;
[key: string]: number;
}
export interface IndicatorPoint {
time: string;
value: number;
}
export interface ArtifactInfo {
name: string;
path: string;
type: string;
size: number;
exists: boolean;
}
export interface PineScriptResult {
exists: boolean;
content: string | null;
}
export interface SessionItem {
session_id: string;
title?: string;
status?: string;
created_at?: string;
updated_at?: string;
last_attempt_id?: string;
}
// --- Goal types ---
export type GoalStatus =
| "active"
| "paused"
| "waiting_user"
| "needs_refresh"
| "insufficient_evidence"
| "compliance_blocked"
| "blocked"
| "budget_limited"
| "usage_limited"
| "complete"
| "cancelled"
| "superseded";
export type GoalRiskTier =
| "research_general"
| "market_specific_short_term"
| "personalized_advice_or_position_sizing";
export interface GoalRecord {
goal_id: string;
session_id: string;
status: GoalStatus;
objective: string;
ui_summary: string;
source: string;
protocol: string;
risk_tier: GoalRiskTier;
token_budget?: number | null;
tokens_used: number;
turn_budget?: number | null;
turns_used: number;
time_budget_seconds?: number | null;
time_used_seconds: number;
budget_wrapup_sent: boolean;
created_at: string;
updated_at: string;
completed_at?: string | null;
recap?: string | null;
}
export interface GoalClaim {
claim_id: string;
goal_id: string;
session_id: string;
claim_type: string;
text: string;
status: string;
created_at: string;
updated_at: string;
}
export interface GoalCriterion {
criterion_id: string;
goal_id: string;
session_id: string;
text: string;
required: boolean;
status: string;
freshness_requirement?: string | null;
protocol_step?: string | null;
created_at: string;
updated_at: string;
}
export interface GoalEvidence {
evidence_id: string;
goal_id: string;
session_id: string;
text: string;
criterion_id?: string | null;
claim_id?: string | null;
evidence_type: string;
tool_call_id?: string | null;
run_id?: string | null;
source_provider?: string | null;
source_type?: string | null;
source_uri?: string | null;
symbol_universe: string[];
benchmark: string[];
timeframe?: string | null;
method?: string | null;
assumptions: Record<string, unknown>;
artifact_path?: string | null;
artifact_hash?: string | null;
retrieved_at: string;
data_as_of?: string | null;
freshness_status: string;
verification_status: string;
confidence?: string | null;
caveat?: string | null;
contradicts_claim_ids: string[];
created_at: string;
}
export interface GoalSnapshot {
goal: GoalRecord;
claims: GoalClaim[];
criteria: GoalCriterion[];
evidence: GoalEvidence[];
evidence_count: number;
}
export interface CreateGoalRequest {
objective: string;
criteria?: string[];
ui_summary?: string;
protocol?: string;
risk_tier?: GoalRiskTier;
token_budget?: number;
turn_budget?: number;
time_budget_seconds?: number;
}
export interface AddGoalEvidenceRequest {
goal_id: string;
expected_goal_id: string;
text: string;
criterion_id?: string | null;
claim_id?: string | null;
evidence_type?: string;
tool_call_id?: string | null;
run_id?: string | null;
source_provider?: string | null;
source_type?: string | null;
source_uri?: string | null;
symbol_universe?: string[];
benchmark?: string[];
timeframe?: string | null;
method?: string | null;
assumptions?: Record<string, unknown>;
artifact_path?: string | null;
artifact_hash?: string | null;
data_as_of?: string | null;
confidence?: string | null;
caveat?: string | null;
contradicts_claim_ids?: string[];
}
export interface UpdateGoalRequest {
goal_id: string;
expected_goal_id: string;
objective?: string;
ui_summary?: string;
}
export interface UpdateGoalResponse {
goal: GoalRecord;
snapshot: GoalSnapshot;
}
export interface AddGoalEvidenceResponse {
evidence: GoalEvidence;
snapshot: GoalSnapshot;
}
export interface GoalAuditRowRequest {
criterion_id: string;
result: string;
evidence_ids?: string[];
notes?: string;
}
export interface UpdateGoalStatusRequest {
goal_id: string;
expected_goal_id: string;
status: GoalStatus;
audit?: GoalAuditRowRequest[];
recap?: string | null;
}
export interface UpdateGoalStatusResponse {
goal: GoalRecord;
snapshot: GoalSnapshot;
}
// --- Alpha Zoo types ---
export interface AlphaListParams {
zoo?: string;
theme?: string;
universe?: string;
limit?: number;
}
export interface AlphaSummary {
id: string;
zoo: string;
theme: string[];
universe: string[];
nickname?: string;
decay_horizon?: number | null;
min_warmup_bars?: number | null;
requires_sector?: boolean;
}
export interface AlphaListResponse {
status: string;
alphas: AlphaSummary[];
total: number;
returned: number;
truncated: boolean;
}
export interface AlphaDetail {
id: string;
zoo: string;
module_path?: string;
meta: Record<string, unknown>;
}
export interface AlphaDetailResponse {
status: string;
alpha: AlphaDetail;
source_code: string;
}
export interface AlphaBenchRequest {
request_id?: string;
zoo: string;
universe: string;
period: string;
top?: number;
alpha_id?: string;
}
export interface AlphaReadiness {
universes: Record<string, { ready: boolean; reason: "public_data" | "tushare_ready" | "tushare_token_missing" | "tushare_dependency_missing" | "single_asset" }>;
zoo_counts: Record<string, number>;
}
export interface AlphaProgress { n_done: number; n_total: number; current_alpha_id?: string; stage?: "loading_data" | "preparing_returns" | "computing" }
export interface AlphaJobSnapshot<T> { job_id: string; status: "queued" | "running" | "done" | "error"; progress: AlphaProgress; result: T | null; error: string | null }
export interface AlphaBenchTopRow {
id: string;
ic_mean: number;
ir: number;
theme: string[];
formula_latex: string;
category: "alive" | "reversed" | "dead";
}
export interface AlphaDataMeta {
fetched_instruments?: number;
requested_instruments?: number;
missing_instruments?: string[];
survivorship_bias?: boolean;
degraded?: boolean;
}
export interface AlphaBenchResult {
n_alphas_tested?: number;
meta?: AlphaDataMeta;
alive: number;
reversed: number;
dead: number;
skipped?: number;
top5_by_ir: AlphaBenchTopRow[];
dead_examples: AlphaBenchTopRow[];
by_theme: Record<string, { alive: number; reversed: number; dead: number }>;
}
export interface AlphaCompareRequest {
request_id?: string;
alpha_ids: string[];
universe: string;
period: string;
/** One of: ir | ic_mean | ic_positive_ratio | ic_count (default ir). */
sort?: string;
}
export interface AlphaCompareRow {
rank: number;
id: string;
zoo: string;
ic_mean: number;
ic_std: number;
ir: number;
ic_positive_ratio: number;
ic_count: number;
/** `delta_<sort>_vs_best` — gap to the top-ranked alpha on the active metric. */
[deltaKey: string]: number | string;
}
export interface AlphaCompareSkip {
id: string;
reason: string;
}
export interface AlphaCompareResult {
meta?: AlphaDataMeta;
universe: string;
period: string;
sort: string;
n_compared: number;
n_skipped: number;
winner: string;
ranking: AlphaCompareRow[];
skipped: AlphaCompareSkip[];
}
// --- Connector runtime channel types ---
/** One mandate profile inside a `mandate.proposal` event (SPEC Consent §1). */
export interface MandateProfile {
ordinal: number;
label: string;
/** Concrete ticker list, or a structural universe descriptor (e.g. "tech_sector"). */
universe: string[] | string;
max_order_usd: number;
daily_trade_cap: number;
/** "none" for cash-only, otherwise a leverage descriptor/multiple. */
leverage: string | number;
instruments: string[];
notes?: string;
}
/** Account block of a `mandate.proposal` event. */
export interface MandateProposalAccount {
broker: string;
type: string;
funded_by: string;
}
/** Payload of the `mandate.proposal` SSE event (SPEC Consent §1). */
export interface MandateProposal {
type?: string;
proposal_id: string;
session_id?: string;
intent_normalized?: string;
account?: MandateProposalAccount;
ceilings_ref?: string;
profiles: MandateProfile[];
funding_note?: string;
halt_note?: string;
/** Present only when this proposal was triggered by a mandate breach (SPEC Consent §3). */
reauth_for?: { breach_id?: string } | null;
}
/** Payload of the `mandate.committed` SSE event (SPEC Consent §1 COMMIT). */
export interface MandateCommitted {
proposal_id?: string;
mandate_id?: string;
consent_record_id?: string;
selected_ordinal?: number;
broker?: string;
/** Resolved limits, surfaced for the compact active-mandate badge. */
max_order_usd?: number;
daily_trade_cap?: number;
expires_at?: string;
}
/** Payload of the `live.halted` SSE event (SPEC Consent §4). */
export interface LiveHalted {
broker?: string | null;
tripped_at?: string;
by?: string;
reason?: string;
}
/** Payload of the `live.action` SSE event (SPEC Consent §5 audit notify). */
export interface LiveAction {
audit_id?: string;
ts?: string;
kind: string;
intent_normalized?: string;
outcome?: string;
broker?: string;
remote_tool?: string;
error?: string | null;
}
export interface CommitMandateRequest {
broker: string;
proposal_id: string;
selected_ordinal: number;
/** Present only on the adjust path (SPEC Consent §3); null otherwise. */
adjustments?: Record<string, unknown> | null;
/** Explicit affirmative consent; the surface sets it on the user's click. */
consent_ack: boolean;
session_id?: string;
account_ref?: string;
lifetime_days?: number;
}
export interface CommitMandateResponse {
mandate_id: string;
consent_record_id: string;
selected_ordinal?: number;
broker?: string;
max_order_usd?: number;
daily_trade_cap?: number;
expires_at?: string;
}
export interface HaltLiveResponse {
halted: boolean;
broker?: string | null;
reason: string;
sentinel: string;
}
export interface LiveAuthorizeRequest {
broker: string;
}
export interface LiveAuthorizeResponse {
broker: string;
connector_profile: string;
oauth_token_present: boolean;
instruction: string;
note?: string;
}
/** Mandate limits surfaced inside a `GET /live/status` broker entry (SPEC §7.5). */
export interface LiveMandateLimits {
max_order_notional_usd?: number;
max_total_exposure_usd?: number;
max_leverage?: number;
max_trades_per_day?: number;
allowed_instruments?: string[];
account_funding_usd?: number;
[key: string]: unknown;
}
/** Active mandate block of a `GET /live/status` broker entry. */
export interface LiveMandateStatus {
broker?: string;
mandate_id?: string;
account_ref?: string;
created_at?: string;
limits?: LiveMandateLimits;
/** ISO timestamp the mandate auto-expires (SPEC §7.5 #7 proactive expiry). */
expires_at?: string;
expires_in_seconds?: number | null;
expired?: boolean;
}
/** Runner liveness block of a `GET /live/status` broker entry (SPEC §7.5 #3). */
export interface LiveRunnerLiveness {
broker?: string;
alive: boolean;
/** Unix epoch seconds of the last heartbeat tick; null if the runner never started. */
last_tick?: number | string | null;
last_tick_age_seconds?: number | null;
}
export interface LiveBrokerAuthStatus {
broker: string;
oauth_token_present: boolean;
is_live_broker: boolean;
/** Optional during rolling upgrades from OAuth-only runtime responses. */
profile_id?: string | null;
transport?: string | null;
connection_state?: string | null;
configured?: boolean | null;
credential_source?: string | null;
sdk_installed?: boolean | null;
last_checked_at?: string | null;
environment_identity?: string | null;
readonly?: boolean | null;
capabilities?: string[] | null;
error_code?: string | null;
error?: string | null;
}
export interface ConnectorVerifyResponse {
status?: string;
profile_id?: string | null;
transport?: string | null;
connection_state?: string | null;
configured?: boolean | null;
credential_source?: string | null;
sdk_installed?: boolean | null;
last_checked_at?: string | null;
environment_identity?: string | null;
readonly?: boolean | null;
capabilities?: string[] | null;
error_code?: string | null;
error?: string | null;
[key: string]: unknown;
}
/** One broker entry in the `GET /live/status` response. */
export interface LiveBrokerStatus {
auth: LiveBrokerAuthStatus;
mandate?: LiveMandateStatus | null;
runner: LiveRunnerLiveness;
halted: boolean;
decision_budget?: LiveDecisionBudget | null;
}
export interface LiveDecisionSettings {
interval_seconds: number;
daily_at: string | null;
timezone: string;
max_daily_turns: number;
max_daily_tokens: number;
max_daily_cost_usd: number | null;
input_usd_per_million: number | null;
output_usd_per_million: number | null;
}
export interface LiveDecisionBudget {
settings?: LiveDecisionSettings;
usage?: { day: string; turns: number; tokens: number; estimated_cost_usd: number | null; unaccounted_turns: number };
projected_daily_cost_usd?: number | null;
error?: string;
}
/** Response of `GET /live/status` (SPEC §7.5 runner status panel + C2). */
export interface LiveStatus {
brokers: LiveBrokerStatus[];
global_halted: boolean;
}
/** Response of `POST /live/runner/start|stop`. */
export interface LiveRunnerResponse {
broker: string;
started?: boolean;
already_running?: boolean;
stopped?: boolean;
was_running?: boolean;
}
export interface MessageItem {
message_id: string;
session_id: string;
role: string;
content: string;
created_at: string;
linked_attempt_id?: string;
metadata?: Record<string, unknown>;
tool_trail?: ToolTrailItem[];
}
export interface ToolTrailItem {
tool: string;
status: "running" | "ok" | "error";
arguments?: Record<string, string>;
elapsed_ms?: number;
preview?: string;
call_id?: string;
timestamp?: number;
}
export interface OfficeSnapshot {
mode: "manual_planning";
agents: { id: string; name: string; role: string; color: string; rank: "Operator" | "Senior" | "Lead"; load: number }[];
tasks: { id: string; title: string; description: string; priority: "low" | "normal" | "high"; assigned_to: string | null; status: "queued" | "assigned" | "completed"; result: string }[];
}
export interface PaperPosition { symbol: string; qty: number; avg_cost: number }
export interface PaperOrder { symbol: string; side: "buy" | "sell"; qty: number; limit?: number }
export interface PaperResult {
code?: string; message?: string;
end_state?: { cash: number; positions: PaperPosition[] };
fills?: { trade_date: string; symbol: string; side: string; qty: number; price: number; fee: number }[];
rejected_orders?: { trade_date: string; symbol: string; reason_code: string }[];
nav_series?: { date: string; nav: number; cash: number }[];
warnings?: string[];
data_provenance?: { source: string; bars_as_of: string | null };
}
export interface PaperAccount {
id: string; label: string; market: "cn_a" | "hk" | "us"; currency: string;
start_on: string; last_date: string | null; revision: number;
account_state: { cash: number; positions: PaperPosition[] };
last_result: PaperResult | null;
}
export const paperApi = {
list: () => request<PaperAccount[]>("/api/paper-accounts"),
create: (body: { label: string; market: string; start: string; account_state: { cash: number; positions: PaperPosition[] } }) =>
request<PaperAccount>("/api/paper-accounts", { method: "POST", body: JSON.stringify(body) }),
advance: (id: string, body: { expected_revision: number; to_date: string; orders?: PaperOrder[]; strategy_path?: string }) =>
request<{ account: PaperAccount; result: PaperResult; committed: boolean }>(`/api/paper-accounts/${encodeURIComponent(id)}/advance`, { method: "POST", body: JSON.stringify(body) }),
history: (id: string) => request<PaperResult[]>(`/api/paper-accounts/${encodeURIComponent(id)}/history`),
};