feat(commonly): commonly_read_attachment — one-shot file read tool#5
Merged
samxu01 merged 1 commit intorebase-2026.3.29from May 7, 2026
Merged
Conversation
Agents had no first-class way to consume files attached in chat. The
[[upload:fileName|...]] directive in `commonly_get_messages` output
gave them the ObjectStore key, but extracting text required a 4-step
reasoning chain: spot the directive, curl the file, pick the right
extractor binary, parse output. Models routinely skipped this and
ignored attachments.
This tool wraps the chain in a single call. Format-aware extraction:
- .docx / .xlsx / .pptx → `officecli view text` (already on PATH)
- .pdf → `pdftotext -layout`
- .md / .txt / .csv / .json / .yaml / .xml / .html / .log → raw utf-8
- everything else → `markitdown` fallback
Returns structured `{ ok, fileName, extractor, sizeBytes, totalChars,
truncated, text }`. Caller can pass `maxChars` (clamped to [1000,
64000]; default 16000) to bound output. Truncation marker preserved
so the model sees what was cut.
Defensive details:
- fileName must match `^[a-zA-Z0-9_.-]+\.[a-zA-Z0-9]+$` and forbid
`..` — can't be tricked into fetching `/etc/passwd` or arbitrary
URLs.
- 25 MB hard cap mirrors the upload route.
- Sends `Authorization: Bearer ${COMMONLY_API_TOKEN}` defensively
even though `/api/uploads/:fileName` is public-read today (ADR-002
Phase 1) — pre-positions us for the signed-URL flip.
- Temp dir is cleaned up in `finally` regardless of extractor outcome.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
samxu01
added a commit
to Team-Commonly/commonly
that referenced
this pull request
May 7, 2026
…ad_attachment tool Picks up Team-Commonly/openclaw#5 — adds commonly_read_attachment to the commonly extension's tool surface. One-shot file read for any attached file in chat, format-aware (officecli / pdftotext / raw utf-8 / markitdown fallback). Replaces the 4-step curl-and-extract reasoning chain agents had to write inline. The dev-time `-dirty` annotation in the submodule is from an unrelated ADR-012 WIP (channel.ts + events.ts) someone else has open in this worktree; the recorded SHA itself is clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
commonly_read_attachment(fileName, maxChars?)tool to the commonly extensionWhy
Agents had no first-class way to consume files attached in chat. The
[[upload:fileName|...]]directive incommonly_get_messagesoutput gave them the ObjectStore key, but extracting text required: spot the directive, curl the file, pick the right extractor binary, parse output. Models routinely skipped this and ignored attachments.Defensive details
^[a-zA-Z0-9_.-]+\.[a-zA-Z0-9]+$+..ban prevents path-traversal / URL-injectionfinallyregardless of extractor outcomeTest plan
pnpm tsgo—tools.tscompiles clean (pre-existing errors in other files are unrelated)pnpm check—tools.tslints cleancommonly_read_attachmenton1778103164116-632900841.docx(real preview-demo.docx); expect text extraction with mammoth-equivalent fidelity