Skip to content

feat(sdk): download a complete attachment with integrity checks - #197

Merged
harshsaver merged 4 commits into
october-dev:mainfrom
nikhilcrypto0:feat/sdk-download-attachment
Nov 13, 2026
Merged

harshsaver merged 4 commits into
october-dev:mainfrom
nikhilcrypto0:feat/sdk-download-attachment

Conversation

@nikhilcrypto0

Copy link
Copy Markdown
Contributor

Closes #182.

Problem

readAttachment() returns one chunk (64 KiB by default). Every SDK consumer had to write its own loop: follow nextOffset, decode base64, check offsets and verify the checksum. A small mistake there returns corrupted or partial files without any error.

Change

client.downloadAttachment(id, { chunkSize?, timeoutMs?, signal? }) returns { attachment, data } with verified bytes. readAttachment() is unchanged. The checks follow the Go CLI's download loop (cmd/agentintercom/attachment.go):

  • Every chunk: the same attachment ID and the expected offset.
  • First chunk: size must be a safe integer from 0 to 16 MiB (the existing MaxAttachmentBytes) and sha256 64 hex characters. Otherwise it stops after that one request. The buffer is allocated once from the checked size.
  • Later chunks: unchanged size and sha256. Bytes may never exceed the declared size.
  • Continuation: must be non-empty and advance exactly to offset + bytes.
  • At the end: the byte count must equal size, and the SHA-256 (WebCrypto, so no Node-only API) must match.
  • Cancellation: request() never sends once the signal is aborted, so no further chunk is requested. timeoutMs applies to each chunk request.
  • Options: chunkSize is validated as 1 to 524288 (the server's MaxAttachmentChunkBytes) before any request.
  • Errors: failures are BusError('INTERNAL', 'Attachment download failed: <reason>'). A bad chunkSize is INVALID_ARGUMENT.

Nothing is written to disk, and there is no new protocol. The README has a short example.

Evidence

Claim How it was checked Result
Multi-chunk download is exact test/attachments.mjs: local fixture server, 200 KB file Bytes equal; requests at offsets 0, 65536, 131072, 196608
Small chunkSize and an empty file Same file, 11 bytes in 4-byte chunks; 0-byte file Correct
Corrupted content, truncated data A byte flipped in chunk 2; nextOffset dropped "SHA-256 does not match"; "received 65536 of 100000 bytes"
Inconsistent metadata Chunk 2 changes size, checksum or ID All rejected
Bad offsets and continuations Shifted offset, skipping nextOffset, empty chunk with a continuation, more bytes than the size, invalid base64 All rejected with specific reasons
Oversized or malformed metadata size over 16 MiB, size -1, bad checksum Rejected after exactly 1 request
Cancellation Aborted before the call; aborted after the first response 0 and 1 requests made, with the abort reason in the error
Real daemon test:integration against a freshly built binary: the existing 5-byte file in 2-byte chunks, plus a 600 KiB upload downloaded with the default chunk size Bytes and SHA-256 match
Each check is tested (mutation check) Removed each check in turn and rebuilt: SHA-256, ID/offset, metadata stability, 16 MiB bound, continuation, truncation, checksum format, chunkSize validation, and dropping the caller's signal All 9 fail a test
Repo checks SDK typecheck, build, test:errors (20 tests, now including attachments.mjs), test:integration; gofmt, go vet ./..., go test -race -count=1 ./... All pass

One note from the mutation check: my first version also checked the signal before each chunk request. Removing that check changed nothing, because request() already refuses to send an aborted request, so I deleted the duplicate. The cancellation tests still pin the behavior.

Not covered

  • Tested with Node 24 on macOS arm64. The browser path uses only fetch, atob and crypto.subtle, but I did not run it in a browser.
  • Files over 16 MiB are refused rather than streamed, matching the server limit and the issue.

@harshsaver harshsaver left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Agentbox PR audit: changes requested

What needs to change

Please apply the fix plan above.

n/a

What this PR changes

  • What it does: Adds one SDK call that fetches a whole shared file and checks that it is complete and uncorrupted before returning it.
  • What changes in the product: Nothing visible in the app, browser or CLI. Developers using the SDK can download a complete file without writing their own download loop.
  • Why it exists: Issue #182 asked for this because every SDK user otherwise has to implement the same checks.
  • Why merge (or why not yet): The implementation meets the requested behavior and all 11 CI checks pass. One small simplification first: use the same download size as the CLI and remove the extra tuning option. A maximum-size file then needs 32 requests instead of 256.
  • What to expect after merging: The feature becomes available when included in a package release. Existing calls are unaffected. Files over 16 MiB are refused. Failed downloads must restart, and bytes downloaded again count toward the transfer allowance. The current PR description will still describe the removed tuning option.
Full audit (Claude (fable, xhigh) × Codex (gpt-6-astra, xhigh), 2 turns, commit b72d039)

PR audit: #197 — feat(sdk): download a complete attachment with integrity checks

Head: b72d039

Sign-off

  • Claude (fable, xhigh): ✅ satisfied — audit complete; decision is fix (one small change we make ourselves, about 37 lines, mostly tests)
  • Codex (gpt-6-astra, xhigh): ✅ satisfied — independently verified the findings and fix plan; no additional blocker or material change required

Decision

fix — use the server-maximum chunk size, matching the CLI, and remove the unnecessary chunk-size option; the integrity checks are sound.

What changes (plain language)

  • What it does: Adds one SDK call that fetches a whole shared file and checks that it is complete and uncorrupted before returning it.
  • What changes in the product: Nothing visible in the app, browser or CLI. Developers using the SDK can download a complete file without writing their own download loop.
  • Why it exists: Issue #182 asked for this because every SDK user otherwise has to implement the same checks.
  • Why merge (or why not yet): The implementation meets the requested behavior and all 11 CI checks pass. One small simplification first: use the same download size as the CLI and remove the extra tuning option. A maximum-size file then needs 32 requests instead of 256.
  • What to expect after merging: The feature becomes available when included in a package release. Existing calls are unaffected. Files over 16 MiB are refused. Failed downloads must restart, and bytes downloaded again count toward the transfer allowance. The current PR description will still describe the removed tuning option.

Findings

Blocking

  • B1 — sdk/typescript/src/client.ts:62-65, 598-601, 608: unnecessary chunkSize option with a 64 KiB default. Small; we fix it ourselves.

    Rule and scope: Harsh asks for the simplest implementation without speculative configuration. Issue #182 requests a complete-download convenience helper while retaining readAttachment() for low-level callers; custom chunk sizing can remain there.

    Reference implementation: The CLI requests bus.MaxAttachmentChunkBytes, 512 KiB (cmd/agentintercom/attachment.go:98; bus/attachments.go:26). The new SDK helper defaults to 65536 bytes.

    Concrete cost: A 16 MiB file takes 256 requests instead of 32. Each successful request authenticates the caller (bus/attachments_transport.go:44-49), opens a SQL transaction, updates transfer usage and acquires the file mutex (bus/attachments.go:463-492; usage update at :264). Each also acquires one of four runtime-wide transfer slots (bus/runtime.go:55; bus/attachments_transport.go:218).

    Failure behavior: An exhausted slot pool immediately returns BACKPRESSURE (bus/attachments_transport.go:18-25). The helper propagates that error without retrying, and previously charged bytes remain charged (spec/0.1/http.md:290; docs/share-files.md:45-46). There are eight times as many request/admission attempts at the smaller default. This establishes additional overhead, not an eightfold failure probability or measured speedup.

    Fallback: If Harsh chooses to retain the knob, default it to 524288. The agreed fix plan removes it.

Non-blocking

  • N1 — sdk/typescript/src/client.ts:582: uploadAttachment still uses the literal 16 * 1024 * 1024 although the PR adds MAX_ATTACHMENT_BYTES at :73. Folded into the existing fix plan as a one-line reuse.

  • N2 — sdk/typescript/src/client.ts:609, 618: malformed-response error consistency. A null or missing result produces a raw TypeError, as does a numeric/object sha256 on a later chunk when size remains unchanged. No corrupt data is returned. The shared request() also trusts successful response shapes (:160-169), and the server’s typed attachment response cannot normally produce these values (bus/attachments.go:39-64). Optional hardening would use chunk?.attachment?.id and explicitly check later checksum types. The first-chunk message “attachment ID or offset changed” is also slightly awkward. No change required for this PR.

  • N3 — sdk/typescript/test/attachments.mjs:136-141: cancellation coverage is narrower than the PR wording suggests. The fixture aborts inside its first request handler, immediately after calling response.end() (:30-32). It exercises cancellation of the first in-flight request, not a controlled boundary after the client has processed a chunk. The implementation still forwards the signal on every iteration (sdk/typescript/src/client.ts:598, 608). For an already-aborted signal, request() aborts its controller and calls fetch with that aborted signal (:129-150); fetch rejects before issuing a network request, as confirmed by Node 20’s implementation. The pre-aborted fixture asserts zero requests (test/attachments.mjs:128-134). This is a test-description limitation, not a demonstrated cancellation bug.

  • N4 — sdk/typescript/src/client.ts:84: atob is acceptable here. Node 20’s documentation labels it Legacy and recommends Buffer.from, but it remains available at the supported runtime floor. The SDK source uses web-standard globals and has no Node type dependency (sdk/typescript/tsconfig.json:6; sdk/typescript/package.json:79-81). Uint8Array.fromBase64 would raise the runtime floor: the compatibility data records Node support starting at 25. No new dependency or compatibility fallback is warranted.

  • N5 — design note, no change requested: A single-request download route already exists: GET /v1/attachments/{id}/content, with X-Content-SHA256 (bus/attachments_transport.go:158-167, 230-246; spec/0.1/http.md:281). The browser uses the corresponding hosted route (web/src/app.js:84-88). The chunk helper satisfies issue #182 and reuses the existing JSON request path, which supplies metadata with each response. Replacing it with the binary route is unnecessary scope.

  • N6 — sdk/typescript/src/client.ts:608: No retry or resume on BACKPRESSURE, matching the CLI’s immediate error return (cmd/agentintercom/attachment.go:98-101). Follow up only if product use demonstrates a need.

  • N7 — sdk/typescript/README.md:139; src/client.ts:593: “Rejects an attachment over 16 MiB before reading it” is loose wording. The first response body has already been received and parsed; rejection happens before base64 decoding, allocating the complete-file buffer or requesting another chunk (src/client.ts:151, 162, 608-621). The fixture correctly expects one request for oversized metadata (test/attachments.mjs:113-123). No change required.

  • N8 — CHANGELOG.md: Untouched, consistent with repository history: only three commits have edited it. CONTRIBUTING.md:48-49 requires tests and public documentation, both supplied here, without requiring a changelog entry for every PR.

  • N9 — GitHub review state: GitHub reports MERGEABLE, BLOCKED and REVIEW_REQUIRED, with no comments or reviews and all 11 checks successful. This is consistent with the maintainer-review requirement in CONTRIBUTING.md:58; it is not a merge conflict. The checked-out head’s parent and local origin/main both equal 056e3200556b2cfb5dfabf5180755b81b0dcfea9.

  • N10 — sdk/typescript/test/attachments.mjs; test/errors.mjs:114-134: additional coverage limits. There is no attachment-specific delayed-response timeout test, successful 16 MiB boundary test or exact-chunk-multiple test. Timeout behavior is covered on the shared request path; the new helper forwards its options on each request and documents a separate timeout per chunk. Boundary cases were traced statically without finding a defect. These gaps do not require expanding the agreed fix.

Fix plan

Line numbers are at head b72d039. The plan is unchanged from turn 1.

sdk/typescript/src/client.ts

  1. Delete lines 62-66: the DownloadAttachmentOptions interface and the blank line after it.
  2. Line 582: replace 16 * 1024 * 1024 with MAX_ATTACHMENT_BYTES (N1).
  3. Line 590: change the JSDoc first line to “Downloads a complete attachment in 512 KiB readAttachment() chunks (the server maximum) and verifies it:”. Leave the rest of the comment.
  4. Lines 597-601: replace the signature, chunkSize destructuring and validation with:
    async downloadAttachment(id: string, options?: OperationOptions): Promise<DownloadedAttachment> {
  5. Line 608:
    const chunk = await this.readAttachment(id, offset, MAX_ATTACHMENT_CHUNK_BYTES, options)

sdk/typescript/test/attachments.mjs

  1. Line 45: randomBytes(200_000) → randomBytes(1_200_000).
  2. Line 51: expected offsets → [0, 524288, 1048576].
  3. Line 52: r.limit === 65536 → r.limit === 524288.
  4. Line 56: rename the test to 'downloads a single-chunk file and an empty file'.
  5. Line 59: drop { chunkSize: 4 }.
  6. Line 61: expected request count 3 → 1.
  7. Lines 70, 80, 94, 108: randomBytes(100_000) → randomBytes(600_000). Leave lines 119 and 130 at 100_000.
  8. Line 84: regex → /received 524288 of 600000 bytes/.
  9. Line 104: Buffer.alloc(100_001) → Buffer.alloc(600_001).
  10. Line 137: randomBytes(300_000) → randomBytes(1_200_000).
  11. Delete lines 143-152: the 'validates chunkSize before any request' test and the blank line before it.

sdk/typescript/test/integration.mjs

  1. Line 127: reviewer.downloadAttachment(file.id, { chunkSize: 2 }) → reviewer.downloadAttachment(file.id). Lines 130-132 stay; the 600 KiB file still exercises two chunks against the real daemon.

sdk/typescript/README.md

  1. Line 139: “follows the chunk continuations” → “follows the chunk continuations (512 KiB per request)”.

Verification after applying the fix, for Harsh’s automation: In sdk/typescript, run npm ci, npm run typecheck, npm run build, npm run test:errors (expect 19 named tests: 7 sessions, 4 CLI, 8 attachments, plus the separate error assertions), and OCTOBER_BUS_BINARY=<fresh build> npm run test:integration. Let CI rerun, including Node 20, 22 and 24.

Message to the developer

Please apply the fix plan above.

n/a

Questions for Harsh

n/a

Verification

  • No contributor code was executed. Neither audit turn installed dependencies or ran tests, builds, type checks or repository scripts. No tracked files or GitHub state were changed. This document supplies the updated audit for automation.
  • Read-only checks performed in turn 2: git status, head/base inspection, the complete five-file diff, git diff --check, source and documentation reads, changelog history, and GitHub PR metadata. The working tree is clean and diff whitespace checks pass.
  • PR description and discussion: The requested gh pr view 197 -R october-dev/october-bus --comments failed because this gh version queried deprecated Projects fields. An explicit --json query succeeded and returned the full description, empty comments/reviews, exact head and 11 successful checks.
  • Issue #182: gh issue view failed to connect. A direct GitHub web read returned the issue’s five acceptance criteria and the contributor’s planning comment. They support the feature scope and existing-protocol approach.
  • Code independently checked in turn 2: The full diff and new attachment fixtures; the shared SDK request/error path, attachment methods, exports, protocol types, runtime/compiler configuration, README and integration test; existing error, session and CLI tests; the Go CLI download loop and its test; server attachment limits, authorization, storage reads, transfer accounting and concurrency slots; route registration, gateway forwarding, browser download behavior, attachment schemas, relevant documentation and CI configuration.
  • Turn 1’s broader coverage remains recorded: Claude read the surrounding SDK, Go attachment implementation, specification, contributing guide and changelog, with no additional blocking finding.
  • Integrity reasoning: Identity and offsets are checked before accepting bytes; initial metadata bounds allocation to 16 MiB; subsequent size/checksum changes reject; extra bytes reject before copying; continuations must advance by a nonempty chunk; final size and SHA-256 must match. Traced empty files, single chunks, exact multiples, short final chunks, boundary sizes, malformed metadata/base64, corruption, truncation and invalid continuations. No path returning unverified or partial bytes was found.
  • Termination reasoning: Every accepted continuation increases the offset by at least one byte while the offset cannot exceed the validated size. An empty chunk with a continuation rejects. Each network request has its own timeout. A small server response can increase request count, but cannot make the continuation loop advance indefinitely.
  • Fix-plan verification: All changed fixtures still reach their intended branches with 512 KiB requests. The 1,200,000-byte success fixture requires offsets 0, 524288 and 1048576. The 600,000-byte corruption/metadata fixtures still reach chunk two; the truncation fixture stops at 524288 bytes; the oversized-data fixture exceeds its declared size. The real-daemon 600 KiB download remains multichunk.
  • Client-side checksum remains necessary: The server verifies SHA-256 only when one read covers the whole file (bus/attachments.go:512-517). A multichunk download needs the helper’s final checksum.
  • Runtime support: Global atob and crypto are available at the Node 20 floor; Node’s WebCrypto documentation confirms SHA-256 accepts typed arrays. The SDK already uses global crypto (sdk/typescript/src/session.ts:43). Browser execution was not verified.
  • CI evidence: All 11 checks at head b72d039 report success. .github/workflows/ci.yml:64-124 includes SDK typecheck/build/tests on Node 24, build/tests on Node 20 and 22, and integration against a freshly built daemon. These results apply to the submitted head, not the proposed fix.
  • Ruleset and scope: No dependency, lockfile, workflow, server protocol or compatibility layer is added. Existing request handling and platform decoding/cryptography are reused. The proposed fix removes unnecessary configuration without changing the required behavior.
  • Transport compatibility: The server explicitly accepts limits through 524288 (bus/attachments_transport.go:141). The gateway forwards the attachment route (internal/gateway/gateway.go:383, 433-452) without a response-size restriction that would prevent the proposed chunk size.

Audit log

  • Turn 1 (Claude (fable, xhigh)): Audited from scratch: full diff, surrounding SDK, CLI and server code, spec, docs, CI config, issue #182 and Node docs. Found the implementation correct and complete against the issue. Raised one small blocking item (B1: unrequested chunkSize option with a default 8× smaller than the CLI's) with an exact fix plan of about 37 lines, plus nine non-blocking notes. Nothing disputed yet.
  • Turn 2 (Codex (gpt-6-astra, xhigh)): Independently verified all findings, the acceptance criteria, CI evidence and every proposed test adjustment; red-teamed integrity, termination, cancellation, timeouts and runtime support. Retained the decision, blocker and exact fix plan. Qualified request-count versus failure-probability wording, corrected the explanation of pre-aborted fetch behavior, and recorded non-blocking coverage limits. No material changes.

Automated review by Harsh's agentbox: two AI reviewers audited this PR against the project ruleset and agreed on it.

Per maintainer review: match the CLI chunk size (bus.MaxAttachmentChunkBytes)
instead of a 64 KiB default, remove the speculative tuning knob, and reuse
MAX_ATTACHMENT_BYTES in uploadAttachment.
@harshsaver

Copy link
Copy Markdown
Member

Applied the review fix on this branch: downloadAttachment now always requests the 512 KiB server maximum (matching the CLI), the chunkSize option is removed, and uploadAttachment reuses MAX_ATTACHMENT_BYTES; tests were rescaled to the new chunk size and the chunkSize validation test removed. Verified with npm run typecheck, build, test:errors (19/19 pass) and test:integration against a freshly built daemon, then merged current main and pushed. Ready for re-review.

@harshsaver harshsaver added the agentbox: ready to merge Audited by Claude and Codex; Harsh can merge label Nov 13, 2026
@harshsaver
harshsaver dismissed their stale review November 13, 2026 04:36

Resolved: the audit of dc5180d found the requested changes in place.

@harshsaver

Copy link
Copy Markdown
Member

🤖 Agentbox PR audit: ready to merge

What this PR changes

  • What it does: Adds one SDK call that downloads a whole shared file and verifies that it is complete and uncorrupted.
  • What changes in the product: Nothing visible in the app, browser or CLI. Developers using the SDK can download a file without writing their own piece-by-piece loop.
  • Why it exists: Issue TypeScript SDK: add a complete attachment download helper with integrity checks #182 asked for this because every SDK user otherwise has to implement the same download and integrity checks.
  • Why merge (or why not yet): The requested simplification is now applied exactly as planned: use the same large pieces as the CLI and remove the extra tuning option. A maximum-size file needs 32 requests instead of 256. No additional blocking defect was found.
  • What to expect after merging: The feature becomes available when included in a package release. Existing calls are unaffected. Files over 16 MiB are refused. Failed downloads must restart, and repeated bytes count again toward the transfer allowance. Before merging, a maintainer must resolve the earlier changes-requested review and satisfy the approval requirement. The stale PR description remains a documentation nit.
Full audit (Claude (fable, xhigh) × Codex (gpt-6-astra, xhigh), 2 turns, commit dc5180d)

PR audit: #197 — feat(sdk): download a complete attachment with integrity checks

Head: dc5180d

Sign-off

  • Claude (fable, xhigh): ✅ satisfied — the one requested fix was applied exactly as planned, nothing new is blocking, and CI is green on this head
  • Codex (gpt-6-astra, xhigh): ✅ satisfied — independently verified the fix, current code and CI evidence; agree with merge, with only non-blocking clarifications

Decision

merge — the earlier blocker is fixed, the merge of main preserves the SDK changes, and all 11 checks pass for the current PR head.

What changes (plain language)

  • What it does: Adds one SDK call that downloads a whole shared file and verifies that it is complete and uncorrupted.
  • What changes in the product: Nothing visible in the app, browser or CLI. Developers using the SDK can download a file without writing their own piece-by-piece loop.
  • Why it exists: Issue TypeScript SDK: add a complete attachment download helper with integrity checks #182 asked for this because every SDK user otherwise has to implement the same download and integrity checks.
  • Why merge (or why not yet): The requested simplification is now applied exactly as planned: use the same large pieces as the CLI and remove the extra tuning option. A maximum-size file needs 32 requests instead of 256. No additional blocking defect was found.
  • What to expect after merging: The feature becomes available when included in a package release. Existing calls are unaffected. Files over 16 MiB are refused. Failed downloads must restart, and repeated bytes count again toward the transfer allowance. Before merging, a maintainer must resolve the earlier changes-requested review and satisfy the approval requirement. The stale PR description remains a documentation nit.

Findings

Blocking

None.

Resolved since the last audit at b72d039:

  • Old B1 is fixed in 5ff8188. downloadAttachment(id, options?: OperationOptions) has no chunk-size option (sdk/typescript/src/client.ts:592). Every request uses MAX_ATTACHMENT_CHUNK_BYTES, 512 KiB (:69, :599), matching the CLI (cmd/agentintercom/attachment.go:98) and server limit (bus/attachments.go:26; bus/attachments_transport.go:141).
  • No chunkSize or DownloadAttachmentOptions reference remains under sdk/.
  • Old N1 is fixed: uploadAttachment reuses MAX_ATTACHMENT_BYTES (sdk/typescript/src/client.ts:577).
  • The fix matches every item of the previous plan across client.ts, test/attachments.mjs, test/integration.mjs and README.md. The subsequent merge of main changes none of those SDK files.

Non-blocking

  • N1 — stale PR description. It still documents the removed chunkSize option, old fixture sizes and “20 tests.” The checked-in README correctly describes 512 KiB requests (sdk/typescript/README.md:139). Updating the PR description is optional. The bodies of recent squash commits 4593e04 and e37dc6f contain branch commit summaries, but those examples do not guarantee what a future squash message will contain; the earlier assertion that stale text would not reach git history was too strong.

  • N2 — sdk/typescript/src/client.ts:600, 609: malformed-response error consistency. A null or missing result throws a raw TypeError. A later checksum that is a number or object also throws TypeError when the size remains unchanged; a missing or null checksum instead reaches the intended BusError. These paths reject without returning corrupt data. The shared request() trusts successful response shapes (:161-165), and normal server responses use typed metadata (bus/attachments.go:39-64). Unchanged from the earlier audit; no required fix.

  • N3 — sdk/typescript/test/attachments.mjs:136-141: cancellation coverage. The “during” case aborts inside the fixture handler immediately after response.end() (:30-32). It tests the first in-flight request, not a controlled boundary after processing a chunk. The implementation forwards the signal on every request (sdk/typescript/src/client.ts:599); the shared request path propagates an already-aborted signal to fetch (:124-145), and the pre-aborted fixture asserts zero network requests (test/attachments.mjs:128-134). No cancellation regression was found.

  • N4 — sdk/typescript/src/client.ts:65: public byte-array type loses buffer precision. Newly noted this round, but the declaration itself is unchanged since b72d039. It exposes plain Uint8Array, while the returned buffer is explicitly Uint8Array<ArrayBuffer> internally (:594, :608). With modern DOM typings, this broader public type can prevent passing data directly to new Blob([data]) or WebCrypto without a copy or type assertion: BlobPart uses BufferSource, whose array views require an ArrayBuffer. This is confirmed by the TypeScript 5.9 declarations and release notes. Declaring the public property as Uint8Array<ArrayBuffer> would improve ergonomics; that generic spelling requires TypeScript 5.7 or newer, as documented in the 5.7 release notes. This does not affect runtime correctness and remains optional. No consumer compilation was run, and no blanket claim is made that a later public-interface change would be non-breaking for every consumer.

  • N5 — sdk/typescript/src/client.ts:120, 599: larger chunks and timeout limits. A full chunk carries 699052 base64 characters plus metadata (spec/0.1/schemas/protocol.schema.json:75). Receiving that uncompressed payload within the default 30-second request timeout implies roughly 190 kbit/s before allowing for other delays. This is an estimate, not a measured connection threshold. Increasing timeoutMs extends only the client deadline; it cannot override the server’s separate 30-second write timeout (bus/server.go:93) or intermediary limits. Go’s server documentation confirms that write timeout applies to response writes. The previous suggestion that a longer client timeout universally solves slow-link failures was too broad. This trade-off does not justify restoring the removed configuration option.

  • N6 — sdk/typescript/src/client.ts:79: atob remains acceptable. Node 20’s documentation labels it Legacy, but it is available at the supported Node ≥20 floor (sdk/typescript/package.json:18-20). It preserves the SDK’s use of web-standard APIs (tsconfig.json:6). Uint8Array.fromBase64 would require Node 25 according to the compatibility data. No dependency or fallback is needed.

  • N7 — existing binary download route. GET /v1/attachments/{id}/content already exists (bus/attachments_transport.go:230-246). Issue #182 asks for a bounded helper over the existing attachment protocol, preserving the low-level chunk operation. Reusing that operation supplies metadata and existing request handling without introducing another client transport path. No redesign requested.

  • N8 — sdk/typescript/src/client.ts:599: no retry or resume on BACKPRESSURE. Errors propagate immediately, matching the CLI (cmd/agentintercom/attachment.go:98-101). Successfully reserved download bytes remain charged, and rereading them consumes allowance again (bus/attachments.go:476, 492; docs/share-files.md:45-46). Follow up only if product use demonstrates a need.

  • N9 — sdk/typescript/README.md:139; src/client.ts:588: oversized-file wording. “Rejects an attachment over 16 MiB before reading it” is loose. The first response has already been received and parsed; rejection precedes base64 decoding, full-file allocation and subsequent requests (src/client.ts:146, 157, 599-612). The oversized-metadata fixture correctly expects one request (test/attachments.mjs:113-123). No required change.

  • N10 — GitHub state and repository hygiene. GitHub reports MERGEABLE, BLOCKED and CHANGES_REQUESTED. The sole review is the earlier automated review against b72d039, posted through Harsh’s account. The new comment reports applying its fix. Maintainer review remains required by CONTRIBUTING.md:58-60; this is not a code conflict. The merge-base, local origin/main and stated base all equal 2604d00. CHANGELOG.md remains untouched, consistent with its sparse history; tests and public documentation are supplied as required by CONTRIBUTING.md:48-49.

  • N11 — coverage limits. There is no attachment-specific slow-response timeout test, successful 16 MiB boundary test or exact-chunk-multiple test. Existing shared-request timeout coverage is at sdk/typescript/test/errors.mjs:114-134. Static tracing found no defect in these paths. The JavaScript fixtures also do not exercise the TypeScript consumer ergonomics described in N4.

Fix plan

n/a

Message to the developer

n/a

Questions for Harsh

n/a

Verification

  • No contributor code was executed. Neither reviewer installed dependencies or ran builds, type checks, tests or repository scripts in this audit round. No tracked files or GitHub state were changed. The updated audit is returned here for automation.

  • Current checkout verified: git rev-parse HEAD returns dc5180d4d58cd084b638710aa27932e401fd788c. The working tree is clean. git diff --check 2604d00936917ab030766d2894b61bbccbf6e4df...HEAD passes.

  • Changes since the earlier audit: Compared b72d039..HEAD and the complete PR diff against 2604d00. Commit 5ff8188 applies the previous fix plan item by item. Commit dc5180d has parents 5ff8188 and 2604d00, an empty combined diff, and no SDK differences from 5ff8188. Main contributes 26 other files; the attachment-adjacent changes concern Go client errors for invalid HTTP responses (bus/attachments_transport.go:333-335; bus/client.go:65-67), not server download behavior.

  • Final scope: Five changed files under sdk/typescript, +230/−2 against the current base. No dependency, lockfile, workflow, protocol or server changes belong to this PR. The existing chunk operation remains unchanged, and the new helper uses existing request handling and platform decoding/cryptography without compatibility layers or speculative configuration.

  • PR discussion reread: gh pr view --comments failed on deprecated Projects fields. An explicit gh pr view --json query succeeded, returning the full description, Harsh’s new comment, the earlier changes-requested review, current head and check rollup. Harsh’s comment reports successful typecheck, build, 19 named tests and integration against a fresh daemon after the fix. The named-test count matches the files: 7 session, 4 CLI and 8 attachment tests, plus the separate error assertions.

  • CI evidence: The current PR rollup reports all 11 checks successful, completed between 23:11 and 23:15 UTC on November 12. The public workflow run also reports success and identifies dc5180d in its page title. .github/workflows/ci.yml:64-124 includes typecheck/build/tests on Node 24, build/tests on Node 20 and 22, and integration against a freshly built daemon. gh run view could not connect, so raw run metadata and logs were not independently inspected.

  • Current code reread: The full five-file PR diff and complete attachment fixture; SDK request/error handling, attachment methods, public exports, protocol types, package/compiler settings and README; integration setup and attachment assertions; shared-request timeout tests; server read limits, transfer accounting, chunk construction, whole-file checksum rule and transfer-slot pool; CLI download behavior; gateway attachment forwarding; schema bounds, contributing policy and CI jobs.

  • All eight attachment fixtures traced at 512 KiB: The 1,200,000-byte success case requests offsets 0, 524288 and 1048576. The 600,000-byte corruption, metadata and shifted-offset cases still reach chunk two. Dropping the first continuation produces “received 524288 of 600000 bytes.” Excess bytes and invalid base64 reject. Empty files, oversized metadata and both cancellation fixtures retain their intended behavior. The integration fixture still downloads 600 KiB in two requests (sdk/typescript/test/integration.mjs:130-132).

  • Integrity and termination rechecked: Identity and offsets are validated before accepting bytes. Initial size is bounded before full-file allocation; subsequent size/checksum changes reject. Excess bytes reject before copying. Each accepted continuation advances by a nonempty chunk while the offset cannot exceed the validated size. Final byte count and SHA-256 must match. No path returning partial or unverified bytes was found. The client checksum remains necessary because the server verifies SHA-256 only when one read covers the complete file (bus/attachments.go:512-517).

  • Cancellation and timeout reasoning: The same operation options reach every request (sdk/typescript/src/client.ts:599), and request failures leave the loop immediately. Timers and abort listeners are cleaned up by the shared request function (:151-154). Timeout is per request, as documented; the helper does not promise a single overall download deadline.

  • Transport compatibility rechecked: The server accepts limits through 524288 (bus/attachments_transport.go:141). The gateway allows and forwards the attachment route without a response-size cap that prevents these chunks (internal/gateway/gateway.go:383, 433-452).

  • External references checked: Issue TypeScript SDK: add a complete attachment download helper with integrity checks #182 and its planning discussion; TypeScript 5.7/5.9 release notes and 5.9.3 DOM declarations; Node 20 globals; compatibility data for Uint8Array.fromBase64; Go’s response-write timeout documentation; and the current CI run page. Browser execution and consumer TypeScript compilation were not performed.

Audit log

  • Earlier round, commit b72d039 — Turn 1 (Claude (fable, xhigh)): Audited from scratch. Found the implementation correct and complete against issue TypeScript SDK: add a complete attachment download helper with integrity checks #182. Raised one small blocker (unrequested chunkSize option with a default 8× smaller than the CLI's) with an exact fix plan, plus non-blocking notes.
  • Earlier round, commit b72d039 — Turn 2 (Codex (gpt-6-astra, xhigh)): Independently verified the findings, CI evidence and every proposed test adjustment; red-teamed integrity, termination, cancellation and runtime support. Kept the decision and fix plan. No material changes.
  • Turn 1 (Claude (fable, xhigh)): Re-audited at dc5180d. Confirmed fix commit 5ff8188 matches the previous fix plan item by item, the merge of main is clean and touches no SDK file, and server limits are unchanged. Re-traced all 8 fixture tests at 512 KiB. Changed the decision from fix to merge and removed the blocker. Added two non-blocking notes (public data type, per-chunk timeout at the larger chunk size) and the stale PR description. Nothing disputed.
  • Turn 2 (Codex (gpt-6-astra, xhigh)): Independently compared both diffs, read the new discussion, verified resolution of the old blocker and rechecked current integrity, cancellation, fixture coverage, server limits and CI. Agreed with merge. Refined only non-blocking claims about squash-message provenance, malformed checksum types, consumer typing and client versus server timeouts. No material changes.

Final checks

Not run here: this PR is from an outside contributor, so its code is never executed on this machine. Rely on CI before merging.

Automated review by Harsh's agentbox: two AI reviewers audited this PR against the project ruleset and agreed on it.

@harshsaver harshsaver left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after the Claude×Codex audit agreed it is ready (audited head dc5180d).

@harshsaver harshsaver left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after the Claude×Codex audit agreed it is ready (audited head dc5180d; this head only adds a merge of main).

@harshsaver harshsaver left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after the Claude×Codex audit agreed it is ready (audited head dc5180d; this head only adds a merge of main).

@harshsaver
harshsaver merged commit b7eb5fa into october-dev:main Nov 13, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agentbox: ready to merge Audited by Claude and Codex; Harsh can merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TypeScript SDK: add a complete attachment download helper with integrity checks

2 participants