Skip to content

FinceptTerminal is a modern finance application offering advanced market analytics, investment research, and economic data tools, designed for interactive exploration and data-driven decision-making in a user-friendly environment.

45.1 KB
Raw Blame
// ExcelTools.cpp — Tools for the Excel/Spreadsheet screen.
//
// 18 tools in category "excel":
//   • Sheet ops (6)  — list, get/set active, add, delete, rename
//   • Cell ops  (3)  — get / set / clear
//   • Sheet data(4)  — get full / set full / get dimensions / recalc
//   • Row/col   (4)  — insert row, insert col, delete rows, delete cols
//   • Export    (1)  — CSV write to disk
//
// xlsx import/export is bound to file-picker dialogs and QXlsx integration —
// out of scope for headless tool use. CSV export is exposed because it's
// fully programmatic via QFile.

#include "mcp/tools/ExcelTools.h"

#include "app/DockScreenRouter.h"
#include "app/WindowFrame.h"
#include "core/logging/Logger.h"
#include "core/window/WindowRegistry.h"
#include "mcp/AsyncDispatch.h"
#include "mcp/ToolSchemaBuilder.h"
#include "mcp/tools/ExportPathGuard.h"
#include "screens/excel/ExcelScreen.h"
#include "screens/excel/SpreadsheetWidget.h"
#include "services/file_manager/FileManagerService.h"

#include <algorithm>

#include <QApplication>
#include <QFile>
#include <QJsonArray>
#include <QJsonObject>
#include <QRegularExpression>
#include <QTabWidget>
#include <QTextStream>

namespace fincept::mcp::tools {

namespace {
static constexpr const char* TAG = "ExcelTools";
static constexpr int kDefaultTimeoutMs = 15000;

// Bulk sheet reads/writes run on the UI thread and repopulate every cell, which
// on a full model is far more work than a single-cell edit. 15 s was not enough:
// set_excel_sheet_data and get_excel_sheet_data were both killed mid-flight,
// leaving a half-written sheet — which is where the stray zeros came from, since
// formulas pointing at cells that never got written evaluate to 0.
static constexpr int kBulkTimeoutMs = 90000;

screens::ExcelScreen* find_excel_screen() {
    for (auto* w : WindowRegistry::instance().frames()) {
        if (!w || !w->dock_router())
            continue;
        auto* dw = w->dock_router()->find_dock_widget("excel");
        if (!dw)
            continue;
        auto* widget = dw->widget();
        if (!widget)
            continue;
        if (auto* es = qobject_cast<screens::ExcelScreen*>(widget))
            return es;
        if (auto* es = widget->findChild<screens::ExcelScreen*>())
            return es;
    }
    return nullptr;
}

// Excel screen, building it on demand.
//
// Screens are lazily constructed (P2), so the Excel screen does not exist until
// the user visits that tab. Every tool here resolved through find_excel_screen()
// and hard-failed with "Excel screen not open" when it wasn't — which meant an
// agent driving Excel from the AI Chat tab could fetch SEC data, plan a full DCF
// model, create the sheet, and then lose 45 consecutive set_excel_cell calls to
// a screen that had simply never been built. Asking the user to go open a tab
// first is not a workable contract for a tool the model calls on its own.
//
// Tools run on the UI thread (run_on_ui), so constructing widgets here is safe.
// Two cases: the dock exists but holds a placeholder (materialize_now builds the
// screen in place, no visible change), or there is no dock at all (navigate
// creates and shows it — the user asked for work in Excel, so surfacing it is
// the expected outcome, and it is the only path that registers the dock).
screens::ExcelScreen* ensure_excel_screen() {
    if (auto* es = find_excel_screen())
        return es;

    // Never restructure the dock layout while a modal dialog is open. Tool
    // bodies are queued onto the UI thread, so they also run inside the nested
    // event loop of a file dialog — navigating there would rebuild docks under
    // a screen that is mid-export and holding pointers into them.
    if (QApplication::activeModalWidget()) {
        LOG_WARN(TAG, "Excel screen missing but a modal dialog is open — refusing to navigate");
        return nullptr;
    }

    for (auto* w : WindowRegistry::instance().frames()) {
        auto* router = w ? w->dock_router() : nullptr;
        if (!router)
            continue;
        if (router->find_dock_widget("excel"))
            router->materialize_now("excel");
        else
            router->navigate("excel");
        if (auto* es = find_excel_screen()) {
            LOG_INFO(TAG, "Excel screen was not open — opened it for a tool call");
            return es;
        }
    }
    LOG_WARN(TAG, "Could not open the Excel screen for a tool call");
    return nullptr;
}

QTabWidget* find_excel_tabs() {
    auto* es = ensure_excel_screen();
    return es ? es->findChild<QTabWidget*>() : nullptr;
}

screens::SpreadsheetWidget* sheet_by_index(int idx) {
    auto* tabs = find_excel_tabs();
    if (!tabs || idx < 0 || idx >= tabs->count())
        return nullptr;
    return qobject_cast<screens::SpreadsheetWidget*>(tabs->widget(idx));
}

screens::SpreadsheetWidget* active_sheet() {
    auto* tabs = find_excel_tabs();
    return tabs ? sheet_by_index(tabs->currentIndex()) : nullptr;
}

screens::SpreadsheetWidget* sheet_by_name(const QString& name) {
    auto* tabs = find_excel_tabs();
    if (!tabs || name.isEmpty())
        return nullptr;
    for (int i = 0; i < tabs->count(); ++i) {
        auto* s = qobject_cast<screens::SpreadsheetWidget*>(tabs->widget(i));
        if (s && s->sheet_name().compare(name, Qt::CaseInsensitive) == 0)
            return s;
    }
    return nullptr;
}

// ── Addressing aliases ──────────────────────────────────────────────────────
//
// These tools address a live Excel *screen*: sheets by integer index, cells by
// zero-based row/col. Every Excel API a model has ever seen — openpyxl,
// xlsxwriter, the Sheets API, VBA — addresses workbooks by file, sheets by NAME
// and cells by A1 reference. So models confidently send
// {workbook_name, tab_name, cell_ref:"B87"}, which matched nothing and failed
// every call; one turn made 15 such calls, had all 15 rejected, and reported a
// finished model anyway.
//
// Rather than expect every model to learn an unusual convention, accept the
// conventional one too. Index/row/col remain canonical; these are aliases.

// "B87" / "$B$87" → row 86, col 1 (both zero-based). False if not A1 notation.
bool parse_a1_ref(const QString& ref, int& row, int& col) {
    static const QRegularExpression re(QStringLiteral("^\\$?([A-Za-z]{1,3})\\$?([0-9]{1,7})$"));
    const auto m = re.match(ref.trimmed());
    if (!m.hasMatch())
        return false;

    const QString letters = m.captured(1).toUpper();
    int c = 0;
    for (const QChar& ch : letters)
        c = c * 26 + (ch.unicode() - 'A' + 1);

    const int r = m.captured(2).toInt();
    if (c <= 0 || r <= 0)
        return false;
    col = c - 1;
    row = r - 1;
    return true;
}

/// Sheet from sheet_index, or the sheet_name/tab_name alias, or the active one.
screens::SpreadsheetWidget* resolve_sheet(const QJsonObject& args) {
    for (const char* key : {"sheet_name", "tab_name"}) {
        const QString name = args.value(QLatin1String(key)).toString().trimmed();
        if (!name.isEmpty()) {
            if (auto* s = sheet_by_name(name))
                return s;
            return nullptr; // named a sheet that doesn't exist — don't silently
                            // fall through to the active one and edit the wrong sheet
        }
    }
    if (args.contains("sheet_index") && !args["sheet_index"].isNull()) {
        const int i = args["sheet_index"].toInt(-1);
        if (i >= 0)
            return sheet_by_index(i);
    }
    return active_sheet();
}

/// Row/col from the explicit integers, or from a cell/cell_ref A1 alias.
/// Returns false when neither was supplied (or the A1 string is malformed).
bool resolve_row_col(const QJsonObject& args, int& row, int& col) {
    if (args.contains("row") && args.contains("col")) {
        row = args["row"].toInt(-1);
        col = args["col"].toInt(-1);
        return row >= 0 && col >= 0;
    }
    for (const char* key : {"cell", "cell_ref", "cell_reference", "ref"}) {
        const QString ref = args.value(QLatin1String(key)).toString();
        if (!ref.isEmpty())
            return parse_a1_ref(ref, row, col);
    }
    return false;
}

/// Declare the alias params so validation accepts them (unknown args are now
/// rejected) and tool_describe advertises them.
ToolSchema with_sheet_aliases(ToolSchema s) {
    ToolParam name_p;
    name_p.type = "string";
    name_p.description = "Sheet name, as an alternative to sheet_index";
    s.params["sheet_name"] = name_p;
    s.params["tab_name"] = name_p; // common synonym

    ToolParam wb;
    wb.type = "string";
    wb.description = "Ignored - there is one live workbook (the Excel screen). Accepted for compatibility.";
    s.params["workbook_name"] = wb;
    return s;
}

ToolSchema with_cell_aliases(ToolSchema s) {
    s = with_sheet_aliases(std::move(s));
    ToolParam cell;
    cell.type = "string";
    cell.description = "Cell in A1 notation (e.g. \"B87\"), as an alternative to row + col";
    s.params["cell"] = cell;
    s.params["cell_ref"] = cell;
    // row/col stay declared but stop being mandatory — either addressing form is
    // valid, so the handler enforces "one of the two" instead.
    if (s.params.contains("row"))
        s.params["row"].required = false;
    if (s.params.contains("col"))
        s.params["col"].required = false;
    s.required.removeAll(QStringLiteral("row"));
    s.required.removeAll(QStringLiteral("col"));
    return s;
}

constexpr const char* kAddressingError =
    "Specify the cell either as row + col (zero-based integers) or as cell=\"B87\" (A1 notation)";

template <typename BodyFn>
void run_on_ui(ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise, BodyFn&& body) {
    AsyncDispatch::callback_to_promise(qApp, std::move(ctx), promise, std::forward<BodyFn>(body));
}
} // namespace

std::vector<ToolDef> get_excel_tools() {
    std::vector<ToolDef> tools;

    // 1. list_excel_sheets
    {
        ToolDef t;
        t.name = "list_excel_sheets";
        t.description = "List all sheets (index, name, rows, cols, is_active).";
        t.category = "excel";
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.async_handler = [](const QJsonObject&, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [](auto resolve) {
                auto* tabs = find_excel_tabs();
                if (!tabs) {
                    resolve(ToolResult::fail("Excel screen could not be opened"));
                    return;
                }
                QJsonArray arr;
                for (int i = 0; i < tabs->count(); ++i) {
                    auto* s = qobject_cast<screens::SpreadsheetWidget*>(tabs->widget(i));
                    if (!s)
                        continue;
                    arr.append(QJsonObject{
                        {"index", i},
                        {"name", s->sheet_name()},
                        {"rows", s->row_count()},
                        {"cols", s->col_count()},
                        {"is_active", i == tabs->currentIndex()},
                    });
                }
                resolve(ToolResult::ok_data(arr));
            });
        };
        tools.push_back(std::move(t));
    }

    // 2. get_excel_active_sheet
    {
        ToolDef t;
        t.name = "get_excel_active_sheet";
        t.description = "Get the currently-active sheet (index + name + dimensions).";
        t.category = "excel";
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.async_handler = [](const QJsonObject&, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [](auto resolve) {
                auto* tabs = find_excel_tabs();
                if (!tabs) {
                    resolve(ToolResult::fail("Excel screen could not be opened"));
                    return;
                }
                auto* s = active_sheet();
                if (!s) {
                    resolve(ToolResult::fail("No active sheet"));
                    return;
                }
                resolve(ToolResult::ok_data(QJsonObject{
                    {"index", tabs->currentIndex()},
                    {"name", s->sheet_name()},
                    {"rows", s->row_count()},
                    {"cols", s->col_count()},
                }));
            });
        };
        tools.push_back(std::move(t));
    }

    // 3. set_excel_active_sheet
    {
        ToolDef t;
        t.name = "set_excel_active_sheet";
        t.description = "Switch to a sheet by index.";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder().integer("sheet_index", "Sheet index").required().min(0).build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* tabs = find_excel_tabs();
                if (!tabs) {
                    resolve(ToolResult::fail("Excel screen could not be opened"));
                    return;
                }
                const int i = args["sheet_index"].toInt();
                if (i < 0 || i >= tabs->count()) {
                    resolve(ToolResult::fail("Index out of range"));
                    return;
                }
                tabs->setCurrentIndex(i);
                resolve(ToolResult::ok("Sheet activated", QJsonObject{{"index", i}}));
            });
        };
        tools.push_back(std::move(t));
    }

    // 4. add_excel_sheet
    {
        ToolDef t;
        t.name = "add_excel_sheet";
        t.description =
            "Add a new blank sheet with an optional name (default: Sheet<N>). Returns the new sheet's index.";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .string("name", "Sheet name (empty = auto-generated)")
                             .default_str("")
                             .length(0, 64)
                             .integer("rows", "Initial row count")
                             .default_int(100)
                             .between(1, 10000)
                             .integer("cols", "Initial col count")
                             .default_int(26)
                             .between(1, 256)
                             .build();
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* tabs = find_excel_tabs();
                if (!tabs) {
                    resolve(ToolResult::fail("Excel screen could not be opened"));
                    return;
                }
                QString name = args["name"].toString();
                if (name.isEmpty())
                    name = QString("Sheet%1").arg(tabs->count() + 1);
                auto* s = new screens::SpreadsheetWidget(name, args["rows"].toInt(100), args["cols"].toInt(26));
                const int idx = tabs->addTab(s, name);
                tabs->setCurrentIndex(idx);
                resolve(ToolResult::ok("Sheet added", QJsonObject{{"index", idx}, {"name", name}}));
            });
        };
        tools.push_back(std::move(t));
    }

    // 5. delete_excel_sheet
    {
        ToolDef t;
        t.name = "delete_excel_sheet";
        t.description = "Delete a sheet by index. Cannot delete the last remaining sheet.";
        t.category = "excel";
        t.is_destructive = true;
        t.auth_required = AuthLevel::ExplicitConfirm;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder().integer("sheet_index", "Sheet index to delete").required().min(0).build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* tabs = find_excel_tabs();
                if (!tabs) {
                    resolve(ToolResult::fail("Excel screen could not be opened"));
                    return;
                }
                const int i = args["sheet_index"].toInt();
                if (i < 0 || i >= tabs->count()) {
                    resolve(ToolResult::fail("Index out of range"));
                    return;
                }
                if (tabs->count() <= 1) {
                    resolve(ToolResult::fail("Cannot delete the last sheet"));
                    return;
                }
                auto* w = tabs->widget(i);
                tabs->removeTab(i);
                if (w)
                    w->deleteLater();
                resolve(ToolResult::ok("Sheet deleted", QJsonObject{{"index", i}}));
            });
        };
        tools.push_back(std::move(t));
    }

    // 6. rename_excel_sheet
    {
        ToolDef t;
        t.name = "rename_excel_sheet";
        t.description = "Rename a sheet (tab label + internal name).";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index")
                             .required()
                             .min(0)
                             .string("name", "New name")
                             .required()
                             .length(1, 64)
                             .build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* tabs = find_excel_tabs();
                if (!tabs) {
                    resolve(ToolResult::fail("Excel screen could not be opened"));
                    return;
                }
                const int i = args["sheet_index"].toInt();
                auto* s = sheet_by_index(i);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                const QString name = args["name"].toString();
                s->set_sheet_name(name);
                tabs->setTabText(i, name);
                resolve(ToolResult::ok("Sheet renamed", QJsonObject{{"index", i}, {"name", name}}));
            });
        };
        tools.push_back(std::move(t));
    }

    // 7. get_excel_cell
    {
        ToolDef t;
        t.name = "get_excel_cell";
        t.description = "Read a cell's raw text (may be a formula starting with '='). Address the cell either as "
                        "row + col (zero-based) or as cell=\"B87\" (A1 notation); the sheet as sheet_index or "
                        "sheet_name.";
        t.category = "excel";
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index (-1 = active)")
                             .default_int(-1)
                             .min(-1)
                             .integer("row", "Zero-indexed row")
                             .required()
                             .min(0)
                             .integer("col", "Zero-indexed column")
                             .required()
                             .min(0)
                             .build();
        t.input_schema = with_cell_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheets"));
                    return;
                }
                int r = -1, c = -1;
                if (!resolve_row_col(args, r, c)) {
                    resolve(ToolResult::fail(kAddressingError));
                    return;
                }
                if (r >= s->row_count() || c >= s->col_count()) {
                    resolve(ToolResult::fail("Cell out of range"));
                    return;
                }
                resolve(ToolResult::ok_data(QJsonObject{
                    {"row", r},
                    {"col", c},
                    {"text", s->cell_text(r, c)},
                }));
            });
        };
        tools.push_back(std::move(t));
    }

    // 8. set_excel_cell
    {
        ToolDef t;
        t.name = "set_excel_cell";
        t.description =
            "Write a cell's text. Strings starting with '=' are evaluated as formulas (e.g. '=A1+B1', "
            "'=SUM(A1:A10)'). Address the cell either as row + col (zero-based) or as cell=\"B87\" (A1 notation); "
            "the sheet as sheet_index or sheet_name.";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index (-1 = active)")
                             .default_int(-1)
                             .min(-1)
                             .integer("row", "Zero-indexed row")
                             .required()
                             .min(0)
                             .integer("col", "Zero-indexed column")
                             .required()
                             .min(0)
                             .string("text", "Cell text (or formula)")
                             .required()
                             .length(0, 4096)
                             .build();
        t.input_schema = with_cell_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheets"));
                    return;
                }
                int r = -1, c = -1;
                if (!resolve_row_col(args, r, c)) {
                    resolve(ToolResult::fail(kAddressingError));
                    return;
                }
                // get_excel_cell range-checks; this path did not. An out-of-range index went
                // straight to QTableWidget::setItem (an invalid-index warning, and a leaked
                // item) and the call still answered "Cell updated" for a write that never
                // happened. A fixed-size sheet needs add_excel_sheet(rows, cols) to grow.
                if (r >= s->row_count() || c >= s->col_count()) {
                    resolve(ToolResult::fail(QString("Cell out of range: the sheet is %1 rows x %2 cols (zero-based "
                                                     "row/col). Use set_excel_sheet_data to extend it, or "
                                                     "add_excel_sheet with larger rows/cols.")
                                                 .arg(s->row_count())
                                                 .arg(s->col_count())));
                    return;
                }
                s->set_cell(r, c, args["text"].toString());
                resolve(ToolResult::ok("Cell updated"));
            });
        };
        tools.push_back(std::move(t));
    }

    // 9. clear_excel_cell
    {
        ToolDef t;
        t.name = "clear_excel_cell";
        t.description = "Clear a cell (set to empty). Address it as row + col (zero-based) or cell=\"B87\".";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index (-1 = active)")
                             .default_int(-1)
                             .min(-1)
                             .integer("row", "Zero-indexed row")
                             .required()
                             .min(0)
                             .integer("col", "Zero-indexed column")
                             .required()
                             .min(0)
                             .build();
        t.input_schema = with_cell_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheets"));
                    return;
                }
                int r = -1, c = -1;
                if (!resolve_row_col(args, r, c)) {
                    resolve(ToolResult::fail(kAddressingError));
                    return;
                }
                if (r >= s->row_count() || c >= s->col_count()) {
                    resolve(ToolResult::fail("Cell out of range"));
                    return;
                }
                s->set_cell(r, c, QString());
                resolve(ToolResult::ok("Cell cleared"));
            });
        };
        tools.push_back(std::move(t));
    }

    // 10. get_excel_sheet_data
    {
        ToolDef t;
        t.name = "get_excel_sheet_data";
        t.description = "Get a sheet's cells as a 2D array of raw cell text (formulas start with '='). By default "
                        "only the used range is returned (row_count/col_count still report the grid size); set "
                        "include_values=true to also get `values`, the computed value of every cell.";
        t.category = "excel";
        t.default_timeout_ms = kBulkTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index (-1 = active)")
                             .default_int(-1)
                             .min(-1)
                             .boolean("include_values", "Also return computed values (formulas evaluated)")
                             .default_bool(false)
                             .boolean("full_grid", "Return the whole padded grid instead of the used range")
                             .default_bool(false)
                             .build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                const bool with_values = args["include_values"].toBool(false);
                const auto data = args["full_grid"].toBool(false) ? s->get_data() : s->get_used_data();
                QJsonArray rows;
                QJsonArray values;
                for (int r = 0; r < data.size(); ++r) {
                    QJsonArray raw_row;
                    QJsonArray value_row;
                    for (int c = 0; c < data[r].size(); ++c) {
                        raw_row.append(data[r][c]);
                        if (with_values)
                            value_row.append(screens::formula::export_text(s->value_at(r, c)));
                    }
                    rows.append(raw_row);
                    if (with_values)
                        values.append(value_row);
                }
                QJsonObject out{
                    {"rows", rows},
                    {"used_rows", static_cast<int>(data.size())},
                    {"row_count", s->row_count()},
                    {"col_count", s->col_count()},
                };
                if (with_values)
                    out["values"] = values;
                resolve(ToolResult::ok_data(out));
            });
        };
        tools.push_back(std::move(t));
    }

    // 11. set_excel_sheet_data
    {
        ToolDef t;
        t.name = "set_excel_sheet_data";
        t.description = "Replace the entire sheet with a 2D array of cell text.";
        t.category = "excel";
        // is_destructive only — NOT ExplicitConfirm. The confirm modal that
        // level waits on was never built, so the checker in AgentService denies
        // everything >= Verified outright and this tool could never run: the
        // chat path got "requires explicit_confirm auth" on every call. Worse,
        // it was inconsistent — set_excel_cell, add_excel_sheet, insert_excel_row
        // and delete_excel_rows are all destructive without the gate, so writing
        // 45 cells one at a time was permitted while writing them in one call
        // was not. is_destructive still blocks the agent path (agents can't
        // prompt); the chat path, where the user is present and watching, is
        // allowed. delete_excel_sheet keeps its gate — it destroys existing work.
        t.is_destructive = true;
        t.default_timeout_ms = kBulkTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index (-1 = active)")
                             .default_int(-1)
                             .min(-1)
                             .array("rows", "2D array of strings (array of row arrays)", QJsonObject{{"type", "array"}})
                             .build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                // This runs on the UI thread and builds a table item per non-empty cell, so an
                // unbounded array from the model could freeze the terminal for minutes. A
                // generous but finite ceiling, reported rather than silently truncated.
                constexpr int kMaxSheetRows = 20000;
                constexpr int kMaxSheetCols = 256;
                const QJsonArray rows_in = args["rows"].toArray();
                if (rows_in.size() > kMaxSheetRows) {
                    resolve(ToolResult::fail(QString("Too many rows (%1) — at most %2 per call").arg(rows_in.size()).arg(kMaxSheetRows)));
                    return;
                }
                QVector<QVector<QString>> data;
                for (const auto& row_v : rows_in) {
                    const QJsonArray cells_in = row_v.toArray();
                    if (cells_in.size() > kMaxSheetCols) {
                        resolve(ToolResult::fail(QString("A row has %1 cells — at most %2 columns").arg(cells_in.size()).arg(kMaxSheetCols)));
                        return;
                    }
                    QVector<QString> row;
                    for (const auto& cell : cells_in) {
                        // QJsonValue::toString() is "" for a number or bool, so a model that sent
                        // [[1, 2.5, true]] — the natural thing for a numeric table — wrote a row of
                        // blank cells and was told the data was replaced.
                        if (cell.isString())
                            row.append(cell.toString());
                        else if (cell.isDouble())
                            row.append(QString::number(cell.toDouble(), 'g', 15));
                        else if (cell.isBool())
                            row.append(cell.toBool() ? QStringLiteral("TRUE") : QStringLiteral("FALSE"));
                        else
                            row.append(QString());
                    }
                    data.append(row);
                }
                s->set_data(data);
                resolve(ToolResult::ok("Sheet data replaced", QJsonObject{{"rows", static_cast<int>(data.size())}}));
            });
        };
        tools.push_back(std::move(t));
    }

    // 12. get_excel_sheet_dimensions
    {
        ToolDef t;
        t.name = "get_excel_sheet_dimensions";
        t.description = "Get row/col counts for a sheet.";
        t.category = "excel";
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema =
            ToolSchemaBuilder().integer("sheet_index", "Sheet index (-1 = active)").default_int(-1).min(-1).build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                resolve(ToolResult::ok_data(QJsonObject{
                    {"name", s->sheet_name()},
                    {"rows", s->row_count()},
                    {"cols", s->col_count()},
                }));
            });
        };
        tools.push_back(std::move(t));
    }

    // 13. recalculate_excel_sheet
    {
        ToolDef t;
        t.name = "recalculate_excel_sheet";
        t.description = "Force recalculation of all formula cells in a sheet.";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kBulkTimeoutMs;
        t.input_schema =
            ToolSchemaBuilder().integer("sheet_index", "Sheet index (-1 = active)").default_int(-1).min(-1).build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                s->recalculate();
                resolve(ToolResult::ok("Recalculated"));
            });
        };
        tools.push_back(std::move(t));
    }

    // 14. insert_excel_row
    {
        ToolDef t;
        t.name = "insert_excel_row";
        t.description = "Insert a row above or below the currently-selected row.";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index (-1 = active)")
                             .default_int(-1)
                             .min(-1)
                             .string("position", "above | below")
                             .default_str("below")
                             .enums({"above", "below"})
                             .build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                if (args["position"].toString("below") == "above")
                    s->insert_row_above();
                else
                    s->insert_row_below();
                resolve(ToolResult::ok("Row inserted"));
            });
        };
        tools.push_back(std::move(t));
    }

    // 15. insert_excel_col
    {
        ToolDef t;
        t.name = "insert_excel_col";
        t.description = "Insert a column to the left or right of the currently-selected column.";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index (-1 = active)")
                             .default_int(-1)
                             .min(-1)
                             .string("position", "left | right")
                             .default_str("right")
                             .enums({"left", "right"})
                             .build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                if (args["position"].toString("right") == "left")
                    s->insert_col_left();
                else
                    s->insert_col_right();
                resolve(ToolResult::ok("Column inserted"));
            });
        };
        tools.push_back(std::move(t));
    }

    // 16. delete_excel_rows
    {
        ToolDef t;
        t.name = "delete_excel_rows";
        t.description = "Delete the currently-selected rows.";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema =
            ToolSchemaBuilder().integer("sheet_index", "Sheet index (-1 = active)").default_int(-1).min(-1).build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                s->delete_selected_rows();
                resolve(ToolResult::ok("Rows deleted"));
            });
        };
        tools.push_back(std::move(t));
    }

    // 17. delete_excel_cols
    {
        ToolDef t;
        t.name = "delete_excel_cols";
        t.description = "Delete the currently-selected columns.";
        t.category = "excel";
        t.is_destructive = true;
        t.default_timeout_ms = kDefaultTimeoutMs;
        t.input_schema =
            ToolSchemaBuilder().integer("sheet_index", "Sheet index (-1 = active)").default_int(-1).min(-1).build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                s->delete_selected_cols();
                resolve(ToolResult::ok("Columns deleted"));
            });
        };
        tools.push_back(std::move(t));
    }

    // 18. export_excel_sheet_csv
    {
        ToolDef t;
        t.name = "export_excel_sheet_csv";
        t.description = "Write a sheet to a CSV file inside the export directory (programmatic, no file dialog). "
                        "'path' is a filename or relative path inside that directory; absolute paths elsewhere "
                        "on disk are refused.";
        t.category = "excel";
        // See set_excel_sheet_data above for why ExplicitConfirm is not used.
        // This is the ONLY tool that persists a sheet to disk, so leaving it
        // gated meant nothing the model built could ever leave memory — a sheet
        // it had just filled in was unreachable from File Manager.
        //
        // That argument covers the CONFIRMATION gate, not the PATH. `path` was
        // still raw model text handed straight to QFile::open(WriteOnly), i.e.
        // arbitrary write anywhere the process can reach. resolve_export_path()
        // confines it without re-gating the tool.
        t.is_destructive = true;
        t.default_timeout_ms = kBulkTimeoutMs;
        t.input_schema = ToolSchemaBuilder()
                             .integer("sheet_index", "Sheet index (-1 = active)")
                             .default_int(-1)
                             .min(-1)
                             .string("path", "Output CSV filename inside the export directory, e.g. 'model.csv'")
                             .required()
                             .length(1, 1024)
                             .build();
        t.input_schema = with_sheet_aliases(std::move(t.input_schema));
        t.async_handler = [](const QJsonObject& args, ToolContext ctx, std::shared_ptr<QPromise<ToolResult>> promise) {
            run_on_ui(std::move(ctx), promise, [args](auto resolve) {
                auto* s = resolve_sheet(args);
                if (!s) {
                    resolve(ToolResult::fail("Sheet not found - call list_excel_sheets for valid sheet_index values"));
                    return;
                }
                const auto dest = resolve_export_path(args["path"].toString());
                if (!dest.ok()) {
                    resolve(ToolResult::fail(dest.error));
                    return;
                }
                QFile f(dest.path);
                if (!f.open(QIODevice::WriteOnly | QIODevice::Text)) {
                    resolve(ToolResult::fail("Cannot open path for writing"));
                    return;
                }
                const auto data = s->get_data();

                // Trim to the used extent. get_data() pads every sheet to at
                // least 100x26, so a 12-row model was exporting as 100 rows of
                // bare commas.
                int last_row = -1;
                int last_col = -1;
                for (int r = 0; r < data.size(); ++r) {
                    for (int c = 0; c < data[r].size(); ++c) {
                        if (!data[r][c].trimmed().isEmpty()) {
                            last_row = std::max(last_row, r);
                            last_col = std::max(last_col, c);
                        }
                    }
                }

                {
                    QTextStream out(&f);
                    out.setEncoding(QStringConverter::Utf8);
                    for (int r = 0; r <= last_row; ++r) {
                        QStringList parts;
                        for (int c = 0; c <= last_col; ++c) {
                            QString cell = (c < data[r].size()) ? data[r][c] : QString();
                            // CSV carries values: formulas export their result.
                            if (cell.startsWith(QLatin1Char('=')))
                                cell = screens::formula::export_text(s->value_at(r, c));
                            else if (cell.startsWith(QLatin1Char('\'')))
                                cell = cell.mid(1);
                            if (cell.contains(',') || cell.contains('"') || cell.contains('\n')) {
                                cell.replace('"', "\"\"");
                                cell = '"' + cell + '"';
                            }
                            parts.append(cell);
                        }
                        out << parts.join(',') << '\n';
                    }
                    out.flush();
                }
                f.close();

                // Register with File Manager, exactly as the UI export buttons
                // do. Without this a model-driven export landed on disk but
                // never appeared in the Files tab — the file existed and was
                // simply invisible, which reads as "the export silently failed".
                const QString out_path = dest.path;
                const QString file_id = services::FileManagerService::instance().import_file(out_path, "excel");

                resolve(ToolResult::ok("CSV exported", QJsonObject{
                                                           {"path", out_path},
                                                           {"rows", last_row + 1},
                                                           {"cols", last_col + 1},
                                                           {"file_manager_id", file_id},
                                                       }));
            });
        };
        tools.push_back(std::move(t));
    }

    LOG_INFO(TAG, QString("Defined %1 excel tools").arg(tools.size()));
    return tools;
}

} // namespace fincept::mcp::tools