feat(tools): the assistant reads the files of records; an answer keeps no address the application did not give #116

Open
james.maes wants to merge 16 commits from feat/read-file-contents into develop
pull from: feat/read-file-contents
Owner

What

The assistant can read the content of a file a record holds, for a person who may open it, and an answer keeps no address the application did not give.

Design: docs/file-contents-and-links.md (short; read it first).

Stacked on #114 (which is stacked on #113, #112 and #115): merge those first; until then this diff shows their commits too.

Why

A person asked what was in a file attached to a record. The assistant found the row of the attachment (a text file of 58 KB), answered that it cannot read the content of files, and wrote an address for the row as plain text: an address it had composed itself.

The rule the assistant is held to: it can see what the signed-in person can see and do what they can do. The exceptions are secrets (credentials, tokens, keys, live sessions) and values masked for that person.

Reading a file: read_file

  • Generic. Which files there are is read from the application's metadata: a BLOB field, or a field (stored or virtual) with a file-download adornment. No table of another QBit is named. describe_table lists a table's file fields. A host can say more for a table (withFileSource), and never has to for a file to be found.
  • As the person, through the application. The record is read as the person (GET /table/{tableName}/{primaryKey}). A BLOB is downloaded with the application's own operation as the person (GET /table/{tableName}/{primaryKey}/{fieldName}/{filename}; new UiApiGateway.download, which streams at most the cap). No internal path.
  • A file kept outside the application (an object store; the record carries an address) is fetched only from a host the code allowed (withFileUrlHosts, none by default): http or https, no credentials, no redirect. The address is never shown to the model.
  • Closed stays closed. A table or a record the person may not read: refused, no content, nothing downloaded. A table closed by the assistant's data access: refused. A field that is masked, hidden or kept from AI: not read (there is no masked version of a file).
  • What comes back. Text as text (plain text, CSV, TSV, JSON, XML, label languages, logs, source); a PDF or a workbook as its text; an image and every other binary described (name, type, size), never dumped.
  • Bounded and honest. At most 2 MB fetched and 20,000 characters per result (both configuration). A part says it is a part ("characters 1 to 20000 of 58112") and which offset reads on.
  • Untrusted. The content is inside the data envelope of tool results (trust="untrusted"; text in the file cannot close it), after a sentence that says it is a file's content and instructions in it are never followed. The system prompt has the same rule (20). The tool-call log keeps what was read, not the content.

Links

  • A file is a chip (a record reference with the file's name). It opens the record the file is attached to when the host said which that is (AssistantFileSource.withAttachedTo) and the application, asked as the person, lists that record's table for them with read permission; otherwise the file's own record, which the person just read.
  • An address the model composes is removed (AnswerLinks). Every path the model was given in a turn (tool results, the conversation so far, the page) is noted. A markdown link to a path of the application that was not given keeps its words and loses its target; a /app/... path written as plain text becomes "(link removed)"; the answer gets one notice. Streamed text that may become a link is held back until it is whole, so the person does not see the address either.
  • On "a table with no screen gets no link": the application's screens open /app/{table}/{id} for every table the application lists for the person with read permission, in an app or not, so whether something opens is asked of the application, per person, not guessed from the metadata (design note, section 3). The links the record tools already gave are for tables they read as the person and are unchanged.

What a host must declare

  • Nothing, for files the application keeps itself (BLOB fields).
  • For files kept outside the application: withFileUrlHosts("files.example.com").
  • Optionally per table: withFileSource(new AssistantFileSource("attachment").withFileNameField(...).withMediaTypeField(...).withSizeField(...).withAttachedTo("recordTable", "recordId")).

No schema change, no permission, no API change. The tool set gains one tool and the system prompt one rule, so the cached request prefix changes once.

Not readable yet

  • Images kept with records: a tool result is text in the provider interface, so an image cannot be handed to a model from a tool. (A person can attach an image to a question.)
  • A PDF without a text layer; a PDF or a workbook larger than the fetch cap; word-processor and presentation files; archives.
  • A file kept elsewhere on a host that is not declared, or one that needs credentials of its own.
  • A file reachable only through an operation of another QBit and not through a field of its record.

Tests (fake model provider, real UI API server)

ReadFileTest:

  • a question answered from a file's text, fetched through the application's download as the person; the chip; the log without the content; describe_table lists the file fields;
  • a long file in parts, and a file larger than the fetch cap, each saying so;
  • a PDF and a workbook as their text, and the workbook says that only its first rows were read;
  • an image, an unknown binary, a record with no file, a table with no files, a field that is not a file;
  • a person without read permission, and a table closed by data access: refused, no content, no download;
  • a masked field: refused, nothing read;
  • an instruction inside a file reaches the model only inside the envelope, which the file cannot close, and nothing else happens;
  • a file kept elsewhere (a virtual field with a file-download adornment): refused until its host is allowed, then read; a place that answers 410; an address that is not of the web; a row with no address;
  • a composed address removed from the streamed and the stored answer while the tool's link stays; the chip opens the record the file is attached to, or the file's own record when the person may not read that one.

AnswerLinksTest: given and composed addresses in every form; what is held back while text streams.

Changed tests: the expected tool lists gain read_file (ToolRegistryTest, WritesFollowThePersonTest, ProcessToolsTest), and chat-tools-before-registry.txt gains its line in the five scenarios that allow every tool (added as text, documented in ChatToolSetTest); the runtime-wiring allow-list of ToolCallArchitectureTest gains withFileSettings.

Build

./mvnw clean verify on this head (77f2b75), nothing skipped: BUILD SUCCESS, 774 tests, 0 failures (651 in qbit-assistant: 645, and 3 each with one and with two processors; 16 provider API, 23 Anthropic, 53 OpenAI-compatible, 11 Bedrock, 12 Vertex, 8 pgvector), coverage checks met in every module.

🤖 Generated with Claude Code

## What The assistant can read the content of a file a record holds, for a person who may open it, and an answer keeps no address the application did not give. Design: `docs/file-contents-and-links.md` (short; read it first). **Stacked on #114** (which is stacked on #113, #112 and #115): merge those first; until then this diff shows their commits too. ## Why A person asked what was in a file attached to a record. The assistant found the row of the attachment (a text file of 58 KB), answered that it cannot read the content of files, and wrote an address for the row as plain text: an address it had composed itself. The rule the assistant is held to: it can see what the signed-in person can see and do what they can do. The exceptions are secrets (credentials, tokens, keys, live sessions) and values masked for that person. ## Reading a file: `read_file` - **Generic.** Which files there are is read from the application's metadata: a BLOB field, or a field (stored or virtual) with a file-download adornment. No table of another QBit is named. `describe_table` lists a table's file fields. A host can say more for a table (`withFileSource`), and never has to for a file to be found. - **As the person, through the application.** The record is read as the person (`GET /table/{tableName}/{primaryKey}`). A BLOB is downloaded with the application's own operation as the person (`GET /table/{tableName}/{primaryKey}/{fieldName}/{filename}`; new `UiApiGateway.download`, which streams at most the cap). No internal path. - **A file kept outside the application** (an object store; the record carries an address) is fetched only from a host the code allowed (`withFileUrlHosts`, none by default): http or https, no credentials, no redirect. The address is never shown to the model. - **Closed stays closed.** A table or a record the person may not read: refused, no content, nothing downloaded. A table closed by the assistant's data access: refused. A field that is masked, hidden or kept from AI: not read (there is no masked version of a file). - **What comes back.** Text as text (plain text, CSV, TSV, JSON, XML, label languages, logs, source); a PDF or a workbook as its text; an image and every other binary described (name, type, size), never dumped. - **Bounded and honest.** At most 2 MB fetched and 20,000 characters per result (both configuration). A part says it is a part ("characters 1 to 20000 of 58112") and which `offset` reads on. - **Untrusted.** The content is inside the data envelope of tool results (`trust="untrusted"`; text in the file cannot close it), after a sentence that says it is a file's content and instructions in it are never followed. The system prompt has the same rule (20). The tool-call log keeps what was read, not the content. ## Links - A file is a **chip** (a record reference with the file's name). It opens the record the file is attached to when the host said which that is (`AssistantFileSource.withAttachedTo`) and the application, asked as the person, lists that record's table for them with read permission; otherwise the file's own record, which the person just read. - **An address the model composes is removed** (`AnswerLinks`). Every path the model was given in a turn (tool results, the conversation so far, the page) is noted. A markdown link to a path of the application that was not given keeps its words and loses its target; a `/app/...` path written as plain text becomes "(link removed)"; the answer gets one notice. Streamed text that may become a link is held back until it is whole, so the person does not see the address either. - On "a table with no screen gets no link": the application's screens open `/app/{table}/{id}` for every table the application lists for the person with read permission, in an app or not, so whether something opens is asked of the application, per person, not guessed from the metadata (design note, section 3). The links the record tools already gave are for tables they read as the person and are unchanged. ## What a host must declare - Nothing, for files the application keeps itself (BLOB fields). - For files kept outside the application: `withFileUrlHosts("files.example.com")`. - Optionally per table: `withFileSource(new AssistantFileSource("attachment").withFileNameField(...).withMediaTypeField(...).withSizeField(...).withAttachedTo("recordTable", "recordId"))`. No schema change, no permission, no API change. The tool set gains one tool and the system prompt one rule, so the cached request prefix changes once. ## Not readable yet - Images kept with records: a tool result is text in the provider interface, so an image cannot be handed to a model from a tool. (A person can attach an image to a question.) - A PDF without a text layer; a PDF or a workbook larger than the fetch cap; word-processor and presentation files; archives. - A file kept elsewhere on a host that is not declared, or one that needs credentials of its own. - A file reachable only through an operation of another QBit and not through a field of its record. ## Tests (fake model provider, real UI API server) `ReadFileTest`: - a question answered from a file's text, fetched through the application's download as the person; the chip; the log without the content; `describe_table` lists the file fields; - a long file in parts, and a file larger than the fetch cap, each saying so; - a PDF and a workbook as their text, and the workbook says that only its first rows were read; - an image, an unknown binary, a record with no file, a table with no files, a field that is not a file; - a person without read permission, and a table closed by data access: refused, no content, no download; - a masked field: refused, nothing read; - an instruction inside a file reaches the model only inside the envelope, which the file cannot close, and nothing else happens; - a file kept elsewhere (a virtual field with a file-download adornment): refused until its host is allowed, then read; a place that answers 410; an address that is not of the web; a row with no address; - a composed address removed from the streamed and the stored answer while the tool's link stays; the chip opens the record the file is attached to, or the file's own record when the person may not read that one. `AnswerLinksTest`: given and composed addresses in every form; what is held back while text streams. Changed tests: the expected tool lists gain `read_file` (`ToolRegistryTest`, `WritesFollowThePersonTest`, `ProcessToolsTest`), and `chat-tools-before-registry.txt` gains its line in the five scenarios that allow every tool (added as text, documented in `ChatToolSetTest`); the runtime-wiring allow-list of `ToolCallArchitectureTest` gains `withFileSettings`. ## Build `./mvnw clean verify` on this head (`77f2b75`), nothing skipped: BUILD SUCCESS, 774 tests, 0 failures (651 in `qbit-assistant`: 645, and 3 each with one and with two processors; 16 provider API, 23 Anthropic, 53 OpenAI-compatible, 11 Bedrock, 12 Vertex, 8 pgvector), coverage checks met in every module. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
james.maes added 21 commits 2026-11-17 21:16:07 +00:00
A confirmed run_process goes through the process's own init and step
operations as the person and passes a screen for them only when it shows
nothing their card did not: its text and inputs were on the card with the
values the process has now, and a review counts exactly the records of the
card and, with every record validated first, has no warning and no error.
Anything else comes back to the person with a new card and nothing stored.

The set is frozen by primary key and by one digest over its records as the
person read them; a set that changed is not run. The card keeps what the
records were (how many, a sample of 20) and lists the whole set by name.

The assistant no longer creates a job: when the application itself hands the
work to a background job, the job is the person's, it is waited for, and its
outcome (rows done, failed and why) is the card's. A job the application
created waiting is cancelled and the run reported as not done.

A change to records of a table is proposed only to a person the application
lets make it (what it tells their own screens); otherwise they are told so
and there is no card.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A person the application refuses is refused before a card where the
application says so beforehand; the confirm-time refusal (a permission that
goes between the card and the confirmation) keeps its tests, with the UI's
own status and message. The tool-set file changes in one description
(run_process), replaced as text.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
docs/one-card-for-a-set.md is the design and the safety argument for parts A
to D; README, UPGRADE, CHANGELOG and the agent notes follow it. UI API
extension assistant 1.11.0 (additive): AssistantActionV1.recordCount,
records and recordsBefore for a run over a set.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A reply that stopped at the output ceiling is read like any other: the tool
calls it had completely formed run, the one it was still writing (its last
part) and any whose input a provider could not read never do and get an
error result that says so. The answer goes on by itself at most
maxOutputContinuations times, each a model call under every limit of any
other; after that it ends INCOMPLETE, never COMPLETE, says what was done and
what was not, and stays in the conversation so that 'continue' goes on.

A provider row lowers the output ceiling of one reply only down to
minOutputTokensPerRequest; it never raises the ceiling the code configured.

An answer shows a record once and at most maxRecordCardsPerTurn record cards
and maxRecordChipsPerTurn record links; a confirmation card is never left
out. The system prompt asks for one proposal for a set and compact answers.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
fix(tools): render_widget follows the assistant's data access; no widget is rendered until a host allows it
maven / build (push) Successful in 8m50s
build / maven (push) Successful in 8m56s
50845aa99b
A widget is code of the application and can show rows of any table, so
render_widget could hand a model the rows of a table the assistant may not
read. The tool now refuses, before the application is asked, every widget
the host did not allow by name (withAllowedWidgetNames, empty by default),
one it hid, and one that reads a table the assistant may not read
(new: withWidgetTables).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
# Conflicts:
#	CHANGELOG.md
#	UPGRADE.md
fix(process): a card shows all a screen says; a screen that says more than a card shows is not passed
maven / build (push) Successful in 9m20s
build / maven (push) Successful in 9m20s
18e893b835
The first card showed the first 300 characters of a screen's text and then
passed the screen. It now shows the whole text (up to 2,000 characters), and
a screen whose text is longer is one the card did not show in full: the run
stops there.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge branch 'feat/one-card-for-a-set' into feat/compact-answers-and-output-ceiling
maven / build (push) Successful in 8m32s
build / maven (push) Successful in 8m32s
4bf102cd4a
fix(tools): a tool call does not hold a monitor while it waits for another thread
maven / build (push) Successful in 9m40s
build / maven (push) Successful in 9m40s
f4b279b95d
A tool call is a virtual thread, and the first call of a turn works out what
the person is offered by waiting for another one. ToolCallService did that
inside synchronized(admission), which keeps the carrier thread: with two
processors a batch of tool calls, and with one processor every first tool
call of a turn, waited out toolCallTimeoutSeconds, and the person was then
offered no write and no process tool for that turn.

An admission is now guarded by a ReentrantLock. FewProcessorsTest runs in
JVMs with one and with two processors (two surefire executions) and fails
there without the fix.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
render_widget rendered a widget that was allowed by name and had no
withWidgetTables entry without any check of what it reads. It now fails
closed: a widget is rendered only when it is allowed, its tables are
declared, and every one of them may be read by the assistant and by the
signed-in person (asked of the application as them).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge branch 'fix/tool-call-admission-does-not-pin' into fix/render-widget-follows-data-access
maven / build (push) Successful in 11m20s
build / maven (push) Successful in 11m20s
2f615879ba
# Conflicts:
#	CHANGELOG.md
Three cases an independent review proved against the first version, each
with a test that fails without its fix:

- a review with a warning and an error was answered with 'validate first'
  before its lines were read, and a process that is not core's streamed one
  went on to store. The lines are now judged first, for every process, and
  'validate first' is only answered for core's own streamed process; a
  review with no lines is not passed.
- a screen outside the process's list of steps (an optional step), with a
  defaulted option, was passed although the card never displayed it. The
  stored proposal now keeps a record of what the card displayed, and a screen
  is passed only against it; a screen the process changed while it ran and
  every screen of a state-machine process stop.
- a job the person may not read was reported as running. A job that was not
  read is reported as exactly that, and the action fails.

Also: a status check cancels nothing; a run still working is 'started and
has not finished'; the names on a card are in the application's order;
every input is on the card, also one left empty.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
docs: remove a conflict marker line left in the changelog by the merge below
maven / build (push) Successful in 8m20s
build / maven (push) Successful in 8m20s
7485fa010f
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
# Conflicts:
#	CHANGELOG.md
test: the tool-set file follows the description of get_run_status
maven / build (push) Successful in 10m8s
build / maven (push) Successful in 10m8s
a5b5f8cc4a
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge branch 'feat/one-card-for-a-set' into feat/compact-answers-and-output-ceiling
maven / build (push) Successful in 10m12s
build / maven (push) Successful in 10m12s
8bf9a557ab
A person asked what was in a file attached to a record. The assistant found
the row of the file, said it cannot read files, and wrote an address it had
composed as plain text.

read_file returns the content of a file a record holds, for a person who
may open it. Which fields are files is read from the metadata (a BLOB, a
field with a file-download adornment); no table of another QBit is named.
The record is read as the person, a BLOB is downloaded with the
application's own operation as the person (UiApiGateway.download), and a
file kept outside the application is fetched only from a host the code
allowed (withFileUrlHosts; no credentials, no redirect). Data access and
field exposure narrow it as for every read: a masked field is not read.
Text comes back as text, a PDF or a workbook as its text, bounded, and a
part says it is a part; an image and any other binary is described, never
dumped. The content is untrusted data inside the envelope, and the
tool-call log does not keep it.

A file is shown as a chip that opens the record it is attached to (when the
host said which, and the application lists that table for the person), or
its own record. An address of the application in an answer is kept only
when a tool result, the conversation or the page gave it (AnswerLinks): a
composed path is removed from the streamed and the stored text.

Design: docs/file-contents-and-links.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
All checks were successful
maven / build (push) Successful in 12m36s
build / maven (push) Successful in 12m35s
You are not authorized to merge this pull request.
This pull request can be merged automatically.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/read-file-contents:feat/read-file-contents
git checkout feat/read-file-contents
Sign in to join this conversation.