[Design] Deliver large AI tool results through previews and retrievable local artifacts

[openai0229]

Context

Chat2DB Community AI tools must keep tool responses small enough for the model context while still making complete execution results available when the model needs more detail.

The current tool paths use fixed bounds in several places, including datasource lists, table lists, table-schema lookup, and SQL row previews. Returning every row inline is not practical, but returning only a preview can hide whether the result is complete.

This design question surfaced while reviewing #1876.

Proposed direction

Use a two-level result model for large AI tool outputs:

1. Return a bounded structured preview in the normal tool response.
2. Materialize the complete available result in a Chat2DB Community local artifact store.
3. Return completeness metadata and an opaque artifact identifier with the preview.
4. Let the model read additional chunks through a dedicated Chat2DB tool when needed.

For example:

{
  "success": true,
  "summary": "Returned 50 of 12438 rows. The complete result is available as an artifact.",
  "data": {
    "preview": {
      "columns": ["id", "name"],
      "rows": []
    },
    "completeness": {
      "complete": false,
      "returnedRows": 50,
      "totalRows": 12438
    },
    "artifact": {
      "id": "art_01K...",
      "format": "jsonl",
      "sizeBytes": 4821932,
      "expiresAt": "2026-07-24T10:00:00Z"
    }
  },
  "errorCode": null
}

The model would retrieve more data through a controlled tool such as:

read_ai_tool_artifact(artifactId, cursor, limit, columns)

The artifact identifier should be opaque. The tool response should not expose an arbitrary local filesystem path because the model cannot access the host filesystem directly and Chat2DB must control which files can be read.

Design questions

1. Does "complete result" mean all rows already fetched by the current execution path, or should Chat2DB stream the entire query result into the artifact?
2. Which local artifact format best preserves column order, SQL nulls, numeric values, temporal values, and large-value metadata while supporting chunked reads?
3. What cursor, row, column-selection, and filtering capabilities should the artifact read tool expose?
4. Which AI tools should support artifacts in the first version: SQL execution only, or metadata and schema tools as well?
5. What expiration time, disk quota, cleanup policy, and failure behavior should the Community local artifact store use?
6. How should the UI expose artifact availability and cleanup without putting the complete result into the model context?

Important implementation boundary

The current SQL tool executes with a bounded page size. Writing the current ExecuteResponse to a file would preserve only the fetched page, not necessarily the complete query result. Producing a genuinely complete artifact may require a separate streaming execution or export path with cancellation, resource limits, and cleanup.

Scope

This discussion covers Chat2DB Community and its local runtime only.

Desired outcome

Agree on the Community result contract, local artifact lifecycle, and read-tool behavior before splitting the work into focused implementation issues.