config.log_cycle

Instructions

Implementation Reference

• src/tools/log-cycle.ts:21-28 (handler)

  The handler function that executes the tool logic: inserts a cycle log into the agent_cycles table and returns a confirmation string.

  export function handleLogCycle(db: Database.Database, input: LogCycleInput): string {
    db.prepare(`
      INSERT INTO agent_cycles (agent_name, strategy, status, positions_open, positions_closed, realized_pnl, unrealized_pnl, win_rate, budget_used, budget_limit, actions_taken, notes)
      VALUES (@agent_name, @strategy, @status, @positions_open, @positions_closed, @realized_pnl, @unrealized_pnl, @win_rate, @budget_used, @budget_limit, @actions_taken, @notes)
    `).run(input);
  
    return `Cycle logged for ${input.agent_name}`;
  }

• src/tools/log-cycle.ts:4-17 (schema)

  Zod schema defining the input validation for config.log_cycle: agent_name, strategy, status, positions_open, positions_closed, realized_pnl, unrealized_pnl, win_rate, budget_used, budget_limit, actions_taken, notes.

  export const logCycleSchema = z.object({
    agent_name: z.string().describe("Name of the AI agent logging this cycle"),
    strategy: z.string().describe("Trading strategy used in this cycle (e.g. 'copy_top_traders', 'stink_bids')"),
    status: z.enum(["ok", "warning", "risk_alert", "error"]).default("ok").describe("Cycle outcome: ok=normal, warning=minor issue, risk_alert=needs attention, error=failed"),
    positions_open: z.number().int().default(0).describe("Number of currently open positions"),
    positions_closed: z.number().int().default(0).describe("Number of positions closed this cycle"),
    realized_pnl: z.number().default(0).describe("Realized profit/loss in USDC from closed positions"),
    unrealized_pnl: z.number().default(0).describe("Unrealized profit/loss in USDC from open positions"),
    win_rate: z.number().default(0).describe("Win rate as a decimal (0.0-1.0)"),
    budget_used: z.number().default(0).describe("Amount of daily budget spent in USDC"),
    budget_limit: z.number().default(0).describe("Total daily budget limit in USDC"),
    actions_taken: z.string().optional().describe("Comma-separated list of actions taken (e.g. 'bought YES on Bitcoin market')"),
    notes: z.string().optional().describe("Free-text notes about this cycle"),
  });

• src/index.ts:288-293 (registration)

  Registration of the tool via server.tool() with name 'config.log_cycle', description, schema, and handler wrapping handleLogCycle.

  server.tool(
    "config.log_cycle",
    "Record an AI agent's trading cycle metrics to the database for dashboard tracking and performance analysis. Stores PnL, win rate, positions, budget usage, and notes. Call this after each automated trading cycle.",
    logCycleSchema.shape,
    safe("agent.log_cycle", (input) => ({ content: [{ type: "text" as const, text: handleLogCycle(db, logCycleSchema.parse(input)) }] }))
  );

• src/db/schema.ts:45-60 (helper)

  Database schema definition for the agent_cycles table that stores the logged cycle data.

  `CREATE TABLE IF NOT EXISTS agent_cycles (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    agent_name TEXT NOT NULL,
    strategy TEXT NOT NULL,
    status TEXT NOT NULL DEFAULT 'ok',
    positions_open INTEGER DEFAULT 0,
    positions_closed INTEGER DEFAULT 0,
    realized_pnl REAL DEFAULT 0,
    unrealized_pnl REAL DEFAULT 0,
    win_rate REAL DEFAULT 0,
    budget_used REAL DEFAULT 0,
    budget_limit REAL DEFAULT 0,
    actions_taken TEXT,
    notes TEXT,
    created_at TEXT DEFAULT (datetime('now'))
  )`,