The assistant can read the content of a file a record holds, for a person who may open it, where a host turns that on. An answer keeps no address of the application that the application did not give.
Design: docs/file-contents-and-links.md (short; read it first).
Off by default: an upgrade changes nothing until a host turns file reading on in code.
Stacked on #114 (which is stacked on #113): 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
Off until a host turns it on: per table (withFileSource) or for every table (withFileReading(true)). Until then the tool is not offered, a call reads nothing, and describe_table names no files.
Generic. Which field is a file 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.
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 is read only with the record it is attached to. Where the host declared what a row is attached to (withAttachedTo, withAttachedToRecordOf), the assistant's data access must allow that record's table and the person must be able to read that record (it is read, as them). A table whose rows name another record and that has no declaration is refused, and the refusal says what to declare.
A file kept outside the application (an object store; the record carries an address) is fetched only from an origin the code allowed (withFileOrigins, none by default): scheme, host and port; https unless an http origin is listed on purpose; no credentials, no redirect, one deadline for the whole fetch including its body. A refusal names neither the address nor its host.
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.
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. A part says it is a part and which offset reads on. A workbook is opened only within a bound on what it inflates to, its rows and cells are walked up to a bound, and taking the text out of a document has a time limit.
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 tool-call log keeps what was read, not the content.
Links
A file is a chip that opens the record it is attached to, or its own record.
An address the model composes is removed (AnswerLinks): a link to a path of the application that was not given keeps its words and loses its target, however it is written (markdown with or without angle brackets, an HTML anchor, relative forms); a /app/... path 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.
Given means written by the application. Outside the envelope of untrusted data every path counts; inside it only the links a tool put there (its href keys); inside a file a person attached, nothing. A path that is only written in the content of a file or a record gives nothing.
Not a control for other sites. An address of another site and an image from one are not judged; the panel that draws the answer is the control for those (design note, section 3).
What a host must declare
Everything; nothing is on by default.
withFileSource(new AssistantFileSource("document")) per table, or withFileReading(true) for all.
For an attachment table: .withAttachedTo("recordTable", "recordId") (or withAttachedToRecordOf, or withStandsAlone()).
For files kept outside the application: withFileOrigins("https://files.example.com").
No schema change, no permission, no API change. The system prompt gains one rule (links), so the cached request prefix changes once; the tool set is unchanged until a host turns file reading on.
Not readable yet
Images kept with records: a tool result is text in the provider interface. (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 an origin 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 (12), AnswerLinksTest (4), FileBoundsTest (4), TableBoundsTest (1); the list is in CHANGELOG.md. The cases a second independent review proved are each a test that fails without its fix: a file attached to a record the person may not read; a body that stalls; other ports and schemes on an allowed host; link forms the first rule passed; a path written in a file's content.
Build
See the comment below for the head and the counts.
## What
The assistant can read the content of a file a record holds, for a person who may open it, where a host turns that on. An answer keeps no address of the application that the application did not give.
Design: `docs/file-contents-and-links.md` (short; read it first).
**Off by default: an upgrade changes nothing until a host turns file reading on in code.**
**Stacked on #114** (which is stacked on #113): 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`
- **Off until a host turns it on:** per table (`withFileSource`) or for every table (`withFileReading(true)`). Until then the tool is not offered, a call reads nothing, and `describe_table` names no files.
- **Generic.** Which field is a file 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.
- **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 is read only with the record it is attached to.** Where the host declared what a row is attached to (`withAttachedTo`, `withAttachedToRecordOf`), the assistant's data access must allow that record's table and the person must be able to read that record (it is read, as them). A table whose rows name another record and that has no declaration is refused, and the refusal says what to declare.
- **A file kept outside the application** (an object store; the record carries an address) is fetched only from an origin the code allowed (`withFileOrigins`, none by default): scheme, host and port; https unless an http origin is listed on purpose; no credentials, no redirect, one deadline for the whole fetch including its body. A refusal names neither the address nor its host.
- **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.
- **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. A part says it is a part and which `offset` reads on. A workbook is opened only within a bound on what it inflates to, its rows and cells are walked up to a bound, and taking the text out of a document has a time limit.
- **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 tool-call log keeps what was read, not the content.
## Links
- A file is a **chip** that opens the record it is attached to, or its own record.
- **An address the model composes is removed** (`AnswerLinks`): a link to a path of the application that was not given keeps its words and loses its target, however it is written (markdown with or without angle brackets, an HTML anchor, relative forms); a `/app/...` path 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.
- **Given means written by the application.** Outside the envelope of untrusted data every path counts; inside it only the links a tool put there (its `href` keys); inside a file a person attached, nothing. A path that is only written in the content of a file or a record gives nothing.
- **Not a control for other sites.** An address of another site and an image from one are not judged; the panel that draws the answer is the control for those (design note, section 3).
## What a host must declare
Everything; nothing is on by default.
- `withFileSource(new AssistantFileSource("document"))` per table, or `withFileReading(true)` for all.
- For an attachment table: `.withAttachedTo("recordTable", "recordId")` (or `withAttachedToRecordOf`, or `withStandsAlone()`).
- For files kept outside the application: `withFileOrigins("https://files.example.com")`.
No schema change, no permission, no API change. The system prompt gains one rule (links), so the cached request prefix changes once; the tool set is unchanged until a host turns file reading on.
## Not readable yet
- Images kept with records: a tool result is text in the provider interface. (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 an origin 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` (12), `AnswerLinksTest` (4), `FileBoundsTest` (4), `TableBoundsTest` (1); the list is in `CHANGELOG.md`. The cases a second independent review proved are each a test that fails without its fix: a file attached to a record the person may not read; a body that stalls; other ports and schemes on an allowed host; link forms the first rule passed; a path written in a file's content.
## Build
See the comment below for the head and the counts.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
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>
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>
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>
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>
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>
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>
A review was passed on its count and its lines alone. A review with an
option whose value the process had changed after the card was made, or with
a value to read, went on to store with what the card never showed (proved
by a second independent review).
A review is a screen too: before it is passed, and before it is answered
with "validate", what it has of its own is held to the record of what the
card displayed (screenDiffers), like any other screen. Such a run stops
with nothing stored, and the card to go on with shows the review's inputs
with the values the process holds now and its values to read. The values
the card gave for a review's own inputs are sent with its answer.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
After a second independent review of reading files and of the link rule:
- Reading files is off by default. A host turns it on per table
(withFileSource) or for every table (withFileReading); until then the
tool is not offered and a call reads nothing.
- A file is read only when the record it is attached to may be read: where
the host declared it (withAttachedTo, withAttachedToRecordOf), the
assistant must be allowed that record's table and the person that record.
An attachment-style table with no declaration is refused, and the refusal
says what to declare.
- A file kept outside the application is fetched only from an allowed
origin (scheme, host and port; https unless an http origin is listed),
with one deadline for the whole fetch, body included. The client is shut
down after each fetch. A refusal names neither the address nor its host.
- Taking the text out of a document is bounded: what a workbook inflates
to, the rows and cells walked, and time.
- The link rule judges every way a path of the application can be written
(angle brackets, an HTML anchor, relative forms), and a path that is only
written in the content of a file or a record no longer counts as given.
The design note says plainly that the panel is the control for addresses
of other sites and for images.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
james.maes
changed title from feat(tools): the assistant reads the files of records; an answer keeps no address the application did not give to feat(tools): the assistant can read the files of records, where a host turns that on; an answer keeps no address the application did not give2026-11-17 22:22:00 +00:00
Second review: what changed (7da70de, merged up as 6e81201)
The description above is rewritten for the result. Per finding:
2. A file was read whatever its parent record is (proved). A row of an attachment table could be read by anyone who may read that table, and the parent decided only the link.
Where a file source declares what a row is attached to (withAttachedTo, new withAttachedToRecordOf), the file is read only when the assistant's data access allows the parent table and the person may read the parent record (it is read, as them). A row that names no record, a record that is not there, and one that is refused give one refusal, with no content, no chip and nothing fetched.
A table whose rows name another record (a table field and a record-id field, FileTools.namesAnotherRecord) with no declaration is not read at all, also with reading on for every table; the refusal says what to declare. withStandsAlone() is the host's statement that a row is attached to nothing.
Tests: ReadFileTest.aFileIsReadOnlyWhenThePersonMayReadTheRecordItIsAttachedTo, anAttachmentTableIsNotReadUntilTheHostDeclaresWhatItsRowsAreAttachedTo. The reviewer's probe returned the content; these assert the refusal.
3. The outside fetch had no deadline on the body (proved: 40 s).
One deadline for the whole fetch, body included (fileFetchSeconds, 20); a place that stalls is given up on and nothing of the file is used. The client is shut down after every fetch.
The allow-list is origins: scheme, host and port (withFileOrigins, replaces withFileUrlHosts); https unless an http origin is listed on purpose; the configuration reports an entry that is not an origin.
No refusal names the address or its host.
Test: ReadFileTest.aFileKeptElsewhereIsFetchedOnlyFromAnAllowedOriginAndWithinOneDeadline (other port, other scheme, look-alike hosts, user name, a secret in the address, a body that stalls: ERROR within the deadline).
4. BLOB content became readable on upgrade. File reading is off by default: withFileSource per table or withFileReading(true); until then the tool is not offered and a call reads nothing. The tool-list expectations and the tool-set file are back to what they were. Test: ReadFileTest.readingFilesIsOffUntilAHostTurnsItOn.
6. Parsing bounds. A workbook is opened only when it inflates to no more than 64 MB in no more than 5,000 parts (inflated in memory to find out, with the library the workbook reader itself uses); rows are walked up to 100,000 rows and 2,000,000 cells; taking the text out of a PDF or a workbook has a time limit (fileParseSeconds, 15). Tests: FileBoundsTest, TableBoundsTest.
5. The link rule. Every way of writing a path of the application is judged (angle brackets, an HTML anchor, relative forms, two slashes). A path that is only written in data does not count as given: inside the envelope of untrusted data only a tool's href keys count, inside an attached file nothing. The design note (section 3, "What this rule is not") says plainly that this is not a control for addresses of other sites or images, and that the panel is. Tests: AnswerLinksTest.aComposedPathIsRemovedHoweverTheLinkIsWritten, aPathWrittenInDataIsNotAnAddressTheApplicationGave, and in ReadFileTest an address inside a file that the model passes on.
Wording. "The address is never shown to the model" is corrected: read_file never puts it in a result; a virtual field is not shown by the record tools, a stored field is shown like any other value unless its AI exposure is narrowed (design note 2.3, upgrade notes).
Not done here: absolute addresses of other sites and images are still not judged (the panel's control, as stated). A workbook parse that ignores its interrupt runs on to its bounds in a background thread after the time limit.
Build:./mvnw clean verify on 6e81201, nothing skipped: BUILD SUCCESS, 787 tests, 0 failures (664 in qbit-assistant: 658, and 3 each with one and with two processors), coverage checks met.
## Second review: what changed (`7da70de`, merged up as `6e81201`)
The description above is rewritten for the result. Per finding:
**2. A file was read whatever its parent record is (proved).** A row of an attachment table could be read by anyone who may read that table, and the parent decided only the link.
- Where a file source declares what a row is attached to (`withAttachedTo`, new `withAttachedToRecordOf`), the file is read only when the assistant's data access allows the parent table **and** the person may read the parent record (it is read, as them). A row that names no record, a record that is not there, and one that is refused give one refusal, with no content, no chip and nothing fetched.
- A table whose rows name another record (a table field and a record-id field, `FileTools.namesAnotherRecord`) with no declaration is not read at all, also with reading on for every table; the refusal says what to declare. `withStandsAlone()` is the host's statement that a row is attached to nothing.
- Tests: `ReadFileTest.aFileIsReadOnlyWhenThePersonMayReadTheRecordItIsAttachedTo`, `anAttachmentTableIsNotReadUntilTheHostDeclaresWhatItsRowsAreAttachedTo`. The reviewer's probe returned the content; these assert the refusal.
**3. The outside fetch had no deadline on the body (proved: 40 s).**
- One deadline for the whole fetch, body included (`fileFetchSeconds`, 20); a place that stalls is given up on and nothing of the file is used. The client is shut down after every fetch.
- The allow-list is origins: scheme, host and port (`withFileOrigins`, replaces `withFileUrlHosts`); https unless an http origin is listed on purpose; the configuration reports an entry that is not an origin.
- No refusal names the address or its host.
- Test: `ReadFileTest.aFileKeptElsewhereIsFetchedOnlyFromAnAllowedOriginAndWithinOneDeadline` (other port, other scheme, look-alike hosts, user name, a secret in the address, a body that stalls: ERROR within the deadline).
**4. BLOB content became readable on upgrade.** File reading is off by default: `withFileSource` per table or `withFileReading(true)`; until then the tool is not offered and a call reads nothing. The tool-list expectations and the tool-set file are back to what they were. Test: `ReadFileTest.readingFilesIsOffUntilAHostTurnsItOn`.
**6. Parsing bounds.** A workbook is opened only when it inflates to no more than 64 MB in no more than 5,000 parts (inflated in memory to find out, with the library the workbook reader itself uses); rows are walked up to 100,000 rows and 2,000,000 cells; taking the text out of a PDF or a workbook has a time limit (`fileParseSeconds`, 15). Tests: `FileBoundsTest`, `TableBoundsTest`.
**5. The link rule.** Every way of writing a path of the application is judged (angle brackets, an HTML anchor, relative forms, two slashes). A path that is only written in data does not count as given: inside the envelope of untrusted data only a tool's `href` keys count, inside an attached file nothing. The design note (section 3, "What this rule is not") says plainly that this is not a control for addresses of other sites or images, and that the panel is. Tests: `AnswerLinksTest.aComposedPathIsRemovedHoweverTheLinkIsWritten`, `aPathWrittenInDataIsNotAnAddressTheApplicationGave`, and in `ReadFileTest` an address inside a file that the model passes on.
**Wording.** "The address is never shown to the model" is corrected: `read_file` never puts it in a result; a virtual field is not shown by the record tools, a stored field is shown like any other value unless its AI exposure is narrowed (design note 2.3, upgrade notes).
**Not done here:** absolute addresses of other sites and images are still not judged (the panel's control, as stated). A workbook parse that ignores its interrupt runs on to its bounds in a background thread after the time limit.
**Build:** `./mvnw clean verify` on `6e81201`, nothing skipped: BUILD SUCCESS, 787 tests, 0 failures (664 in `qbit-assistant`: 658, and 3 each with one and with two processors), coverage checks met.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
A one-page PDF of six million glyphs is 17 KB, and PDFBox keeps the
position of every glyph of a page until the page ends: reading it through
read_file, or as a file attached to a question, exhausted a heap of 1 GB
whatever the caps on pages and characters (found by an independent review).
PdfText counts glyphs as they are taken and stops past a bound: twice the
characters asked for, never more than 200,000. What was taken of the page
is written, and the text is reported as truncated. read_file takes at most
100,000 characters out of one document instead of all of it.
PdfGlyphBoundTest reads that file through both routes. Before the bound
read_file handed over all 6,000,000 characters and the attachment route
allocated 3,992 MB; with it, 94 MB.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A 17 KB PDF exhausted the heap. A one-page PDF of 6,000,000 glyphs, read through read_file or as a file attached to a question: PDFBox keeps the position of every glyph of a page until the page ends, so the caps on pages and characters did not bound it, and read_file asked for all of the text.
Fix:
PdfText counts glyphs as they are taken and stops past a bound: twice the characters asked for, never more than 200,000 (PdfText.MAX_GLYPHS). That is 200,000 for read_file and 100,000 for an attachment at the default 50,000 characters. What was taken of the page is written, and the text is reported as truncated like the other bounds. One fix for both routes.
read_file takes at most 100,000 characters out of one document (FileTools.MAX_DOCUMENT_CHARS; five results at the default 20,000) instead of all of it.
Test:PdfGlyphBoundTest builds the reviewer's PDF (17,365 bytes) and reads it through read_file and through the attachment extraction; both must return a truncated result with no error, soon, and within their caps. Run against the code before the fix (only the two constants added so that it compiles), both failed: read_file handed over totalChars 6,000,000 after 8.5 s, and the attachment route allocated 3,992 MB. With the fix: 94 MB allocated, about a second each.
Design note (section 2.4), changelog and upgrade notes state the caps. The branch is up to date with develop (dac309c).
## Confirmation pass: the one blocker (`3f93119`)
**A 17 KB PDF exhausted the heap.** A one-page PDF of 6,000,000 glyphs, read through `read_file` or as a file attached to a question: PDFBox keeps the position of every glyph of a page until the page ends, so the caps on pages and characters did not bound it, and `read_file` asked for all of the text.
**Fix:**
- `PdfText` counts glyphs as they are taken and stops past a bound: twice the characters asked for, never more than 200,000 (`PdfText.MAX_GLYPHS`). That is 200,000 for `read_file` and 100,000 for an attachment at the default 50,000 characters. What was taken of the page is written, and the text is reported as truncated like the other bounds. One fix for both routes.
- `read_file` takes at most 100,000 characters out of one document (`FileTools.MAX_DOCUMENT_CHARS`; five results at the default 20,000) instead of all of it.
**Test:** `PdfGlyphBoundTest` builds the reviewer's PDF (17,365 bytes) and reads it through `read_file` and through the attachment extraction; both must return a truncated result with no error, soon, and within their caps. Run against the code before the fix (only the two constants added so that it compiles), both failed: `read_file` handed over `totalChars` 6,000,000 after 8.5 s, and the attachment route allocated 3,992 MB. With the fix: 94 MB allocated, about a second each.
Design note (section 2.4), changelog and upgrade notes state the caps. The branch is up to date with `develop` (`dac309c`).
**Build:** `./mvnw clean verify` on `3f93119`, nothing skipped: BUILD SUCCESS, 789 tests, 0 failures, coverage checks met.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
What
The assistant can read the content of a file a record holds, for a person who may open it, where a host turns that on. An answer keeps no address of the application that the application did not give.
Design:
docs/file-contents-and-links.md(short; read it first).Off by default: an upgrade changes nothing until a host turns file reading on in code.
Stacked on #114 (which is stacked on #113): 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_filewithFileSource) or for every table (withFileReading(true)). Until then the tool is not offered, a call reads nothing, anddescribe_tablenames no files.GET /table/{tableName}/{primaryKey}). A BLOB is downloaded with the application's own operation as the person (GET /table/{tableName}/{primaryKey}/{fieldName}/{filename}; newUiApiGateway.download, which streams at most the cap). No internal path.withAttachedTo,withAttachedToRecordOf), the assistant's data access must allow that record's table and the person must be able to read that record (it is read, as them). A table whose rows name another record and that has no declaration is refused, and the refusal says what to declare.withFileOrigins, none by default): scheme, host and port; https unless an http origin is listed on purpose; no credentials, no redirect, one deadline for the whole fetch including its body. A refusal names neither the address nor its host.offsetreads on. A workbook is opened only within a bound on what it inflates to, its rows and cells are walked up to a bound, and taking the text out of a document has a time limit.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 tool-call log keeps what was read, not the content.Links
AnswerLinks): a link to a path of the application that was not given keeps its words and loses its target, however it is written (markdown with or without angle brackets, an HTML anchor, relative forms); a/app/...path 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.hrefkeys); inside a file a person attached, nothing. A path that is only written in the content of a file or a record gives nothing.What a host must declare
Everything; nothing is on by default.
withFileSource(new AssistantFileSource("document"))per table, orwithFileReading(true)for all..withAttachedTo("recordTable", "recordId")(orwithAttachedToRecordOf, orwithStandsAlone()).withFileOrigins("https://files.example.com").No schema change, no permission, no API change. The system prompt gains one rule (links), so the cached request prefix changes once; the tool set is unchanged until a host turns file reading on.
Not readable yet
Tests (fake model provider, real UI API server)
ReadFileTest(12),AnswerLinksTest(4),FileBoundsTest(4),TableBoundsTest(1); the list is inCHANGELOG.md. The cases a second independent review proved are each a test that fails without its fix: a file attached to a record the person may not read; a body that stalls; other ports and schemes on an allowed host; link forms the first rule passed; a path written in a file's content.Build
See the comment below for the head and the counts.
🤖 Generated with Claude Code
feat(tools): the assistant reads the files of records; an answer keeps no address the application did not giveto feat(tools): the assistant can read the files of records, where a host turns that on; an answer keeps no address the application did not giveSecond review: what changed (
7da70de, merged up as6e81201)The description above is rewritten for the result. Per finding:
2. A file was read whatever its parent record is (proved). A row of an attachment table could be read by anyone who may read that table, and the parent decided only the link.
withAttachedTo, newwithAttachedToRecordOf), the file is read only when the assistant's data access allows the parent table and the person may read the parent record (it is read, as them). A row that names no record, a record that is not there, and one that is refused give one refusal, with no content, no chip and nothing fetched.FileTools.namesAnotherRecord) with no declaration is not read at all, also with reading on for every table; the refusal says what to declare.withStandsAlone()is the host's statement that a row is attached to nothing.ReadFileTest.aFileIsReadOnlyWhenThePersonMayReadTheRecordItIsAttachedTo,anAttachmentTableIsNotReadUntilTheHostDeclaresWhatItsRowsAreAttachedTo. The reviewer's probe returned the content; these assert the refusal.3. The outside fetch had no deadline on the body (proved: 40 s).
fileFetchSeconds, 20); a place that stalls is given up on and nothing of the file is used. The client is shut down after every fetch.withFileOrigins, replaceswithFileUrlHosts); https unless an http origin is listed on purpose; the configuration reports an entry that is not an origin.ReadFileTest.aFileKeptElsewhereIsFetchedOnlyFromAnAllowedOriginAndWithinOneDeadline(other port, other scheme, look-alike hosts, user name, a secret in the address, a body that stalls: ERROR within the deadline).4. BLOB content became readable on upgrade. File reading is off by default:
withFileSourceper table orwithFileReading(true); until then the tool is not offered and a call reads nothing. The tool-list expectations and the tool-set file are back to what they were. Test:ReadFileTest.readingFilesIsOffUntilAHostTurnsItOn.6. Parsing bounds. A workbook is opened only when it inflates to no more than 64 MB in no more than 5,000 parts (inflated in memory to find out, with the library the workbook reader itself uses); rows are walked up to 100,000 rows and 2,000,000 cells; taking the text out of a PDF or a workbook has a time limit (
fileParseSeconds, 15). Tests:FileBoundsTest,TableBoundsTest.5. The link rule. Every way of writing a path of the application is judged (angle brackets, an HTML anchor, relative forms, two slashes). A path that is only written in data does not count as given: inside the envelope of untrusted data only a tool's
hrefkeys count, inside an attached file nothing. The design note (section 3, "What this rule is not") says plainly that this is not a control for addresses of other sites or images, and that the panel is. Tests:AnswerLinksTest.aComposedPathIsRemovedHoweverTheLinkIsWritten,aPathWrittenInDataIsNotAnAddressTheApplicationGave, and inReadFileTestan address inside a file that the model passes on.Wording. "The address is never shown to the model" is corrected:
read_filenever puts it in a result; a virtual field is not shown by the record tools, a stored field is shown like any other value unless its AI exposure is narrowed (design note 2.3, upgrade notes).Not done here: absolute addresses of other sites and images are still not judged (the panel's control, as stated). A workbook parse that ignores its interrupt runs on to its bounds in a background thread after the time limit.
Build:
./mvnw clean verifyon6e81201, nothing skipped: BUILD SUCCESS, 787 tests, 0 failures (664 inqbit-assistant: 658, and 3 each with one and with two processors), coverage checks met.🤖 Generated with Claude Code
Confirmation pass: the one blocker (
3f93119)A 17 KB PDF exhausted the heap. A one-page PDF of 6,000,000 glyphs, read through
read_fileor as a file attached to a question: PDFBox keeps the position of every glyph of a page until the page ends, so the caps on pages and characters did not bound it, andread_fileasked for all of the text.Fix:
PdfTextcounts glyphs as they are taken and stops past a bound: twice the characters asked for, never more than 200,000 (PdfText.MAX_GLYPHS). That is 200,000 forread_fileand 100,000 for an attachment at the default 50,000 characters. What was taken of the page is written, and the text is reported as truncated like the other bounds. One fix for both routes.read_filetakes at most 100,000 characters out of one document (FileTools.MAX_DOCUMENT_CHARS; five results at the default 20,000) instead of all of it.Test:
PdfGlyphBoundTestbuilds the reviewer's PDF (17,365 bytes) and reads it throughread_fileand through the attachment extraction; both must return a truncated result with no error, soon, and within their caps. Run against the code before the fix (only the two constants added so that it compiles), both failed:read_filehanded overtotalChars6,000,000 after 8.5 s, and the attachment route allocated 3,992 MB. With the fix: 94 MB allocated, about a second each.Design note (section 2.4), changelog and upgrade notes state the caps. The branch is up to date with
develop(dac309c).Build:
./mvnw clean verifyon3f93119, nothing skipped: BUILD SUCCESS, 789 tests, 0 failures, coverage checks met.🤖 Generated with Claude Code