Check budget status

Instructions

Implementation Reference

• mcp/server.ts:248-276 (registration)

  Registration of the 'l402_set_budget' tool on the MCP server with its schema (title, description, inputSchema, annotations) and the async handler callback.

  // Tool: l402_set_budget
  server.registerTool(
    "l402_set_budget",
    {
      title: "Check budget status",
      description:
        "Returns the session budget cap configured at startup (via BUDGET_SATS env var). " +
        "Use this to confirm what hard spending limit is in effect — useful at the start of a session before making any API calls. " +
        "Read-only: this tool CANNOT set or change the budget at runtime. " +
        "To raise or lower the cap, stop and restart the MCP server with a different BUDGET_SATS value. " +
        "For remaining balance during a session, use l402_balance instead.",
      inputSchema: {},
      annotations: {
        readOnlyHint: true,
        idempotentHint: true,
      },
    },
    async () => {
      const report = requireClient().spendingReport();
      return {
        content: [{
          type: "text" as const,
          text: report
            ? `Budget: ${budgetSats} sats total, ${report.remaining} remaining.`
            : `No budget configured (BUDGET_SATS not set).`,
        }],
      };
    }
  );

• mcp/server.ts:265-275 (handler)

  The handler function for l402_set_budget. Calls client.spendingReport() and returns the budget cap (budgetSats) and remaining balance, or a message if no budget is configured.

  async () => {
    const report = requireClient().spendingReport();
    return {
      content: [{
        type: "text" as const,
        text: report
          ? `Budget: ${budgetSats} sats total, ${report.remaining} remaining.`
          : `No budget configured (BUDGET_SATS not set).`,
      }],
    };
  }

• mcp/server.ts:251-263 (schema)

  Schema definition for l402_set_budget: title='Check budget status', description explaining it's read-only and returns the BUDGET_SATS cap, empty inputSchema, and readOnlyHint/idempotentHint annotations.

  {
    title: "Check budget status",
    description:
      "Returns the session budget cap configured at startup (via BUDGET_SATS env var). " +
      "Use this to confirm what hard spending limit is in effect — useful at the start of a session before making any API calls. " +
      "Read-only: this tool CANNOT set or change the budget at runtime. " +
      "To raise or lower the cap, stop and restart the MCP server with a different BUDGET_SATS value. " +
      "For remaining balance during a session, use l402_balance instead.",
    inputSchema: {},
    annotations: {
      readOnlyHint: true,
      idempotentHint: true,
    },

• src/client.ts:96-100 (helper)

  The spendingReport() method on L402Client that delegates to BudgetTracker.report() to produce the SpendingReport object.

  /** Returns a spending report. Only available when budgetSats is configured. */
  spendingReport() {
    if (!this.budget) return null;
    return this.budget.report();
  }

• src/agent/budget.ts:60-67 (helper)

  The BudgetTracker.report() method that compiles the SpendingReport (total spent, remaining, byDomain breakdown, transaction list) used by the l402_set_budget handler.

  report(): SpendingReport {
    return {
      total: this.spent,
      remaining: Math.max(0, this.limitSats - this.spent),
      byDomain: { ...this.byDomain },
      transactions: [...this.transactions],
    };
  }