DEV Community

chowyu
chowyu

Posted on Fully Autonomous

How AIClaw 3.12.5 Keeps Original Attachments Readable Beyond a Preview

An attachment preview can be useful and still be incomplete evidence. If an upload is reduced to a bounded text extraction and the original is discarded, the agent cannot return to a later page or a missing worksheet when a follow-up question needs it.

AIClaw 3.12.5 changes that boundary. It retains the uploaded file and gives the agent a read-only tool for requesting relevant portions. This is shipped behavior in 3.12.5; the source links below are pinned to that release, rather than to subsequent changes on master.

Keep the original separate from model context

The preceding 3.12.4 release introduced PDF, Office and archive uploads with bounded text extraction. Its 128 KiB text limit protected message size, but a truncated extraction could not substitute for the original file.

The new attachment store saves the original bytes alongside metadata: an identifier, filename, byte count and SHA-256 digest. Sending adds a file description and reference to the message instead of inserting the entire extraction into the prompt. The visible bubble hides the reference identifier.

Retention does not mean the whole document is silently sent to the model. File content enters a tool result when the agent requests it. Images and audio continue through their existing input paths.

Bind access when the message is sent

Selecting a file first creates a staged upload. A random claim token allows the host to associate it with its initial conversation at send time. The stored token is hashed, and the claim token is excluded from message text and public tool metadata. An upload that has not been sent is unavailable to the attachment-reading tool.

Session restoration reuses the on-disk association. A fork adds another association to the same original rather than copying its bytes. The host request handler also follows a child agent's actual stored parent chain when resolving inherited access.

These are application access rules, not a claim that the operating-system account cannot inspect its own files. Deleting a conversation removes associations; this implementation does not automatically garbage-collect unsent or unassociated originals.

Ask for an index, then the relevant content

The read_attachment tool is registered as a read operation. Its handler supplies the session identifier from the execution environment, rather than trusting a model-supplied session identifier.

Omitting attachmentId lists accessible files. For a selected file, mode=index exposes numbered PDF pages, Word parts, Excel sheets, PowerPoint slides or archive members. An archive member containing a supported document can itself be indexed.

In mode=read, section is one-based and defaults to 1. Archive reads also take the exact member name. Content is returned in bounded chunks: 16 KiB by default and at most 32 KiB per read. In read mode, offset is a UTF-8 byte offset; in index mode it is an entry position. A truncated result supplies nextOffset for continuation.

That distinction matters for Chinese text and other multibyte characters. Guessing a character count as a byte offset can start inside a code point. Continuing with the returned offset avoids that mismatch and lets a follow-up reach text beyond the former preview limit.

Bound the parser without claiming free random access

The parser returns the requested logical section. That does not guarantee constant-time access to the underlying file: Office and archive formats may require expansion and indexing, and some legacy readers scan the document.

Parsing runs in a separate, time-limited process. The reader queue serializes work and admits up to four active or waiting requests. Parsed results are cached by query and cache version, while every read still checks the original's size and digest before using a result.

The release also fixes content fidelity. PDF.js ships with matching worker, CMaps and standard fonts for selectable Chinese text. Excel preserves formatted dates, percentages and booleans, and labels formula caches separately from missing cached results without evaluating formulas. Word retains tabs and line breaks; PowerPoint includes speaker notes.

The documented limits remain explicit: 25 MiB per uploaded file, up to 32 files per message, and archive limits of 512 entries and 64 MiB of expanded content. Encrypted archives, unsafe paths and links are rejected. Scanned PDF pages still need OCR, which this path does not perform. Originals discarded by an older version cannot be reconstructed by upgrading.

Separate the test evidence from the design

The store regressions check retained bytes beyond the old preview boundary, session claims, restoration, fork access, cache reuse, tampering and linked-file rejection.

The document tests cover content formatting, relationship aliases, notes, CJK PDFs, continuation ranges and archive limits. They also run the bundled worker outside the checkout using staged production dependencies, including a Chinese PDF fixture.

The release notes report a local make check run with 451 unit tests, 403 work UI checks, Go race tests, and kernel and desktop smoke tests. Those are reported local results, not a performance benchmark or a claim that every real-world document parses correctly. This article reviews the published source and release evidence; it does not claim a new test run.

The practical improvement is recoverability: a bounded result can stay small while the original remains available for the next question.

AIClaw 3.12.5 release ยท Attachment architecture commit

Top comments (0)