diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md index 492cff9..ae45e30 100644 --- a/sdk/typescript/README.md +++ b/sdk/typescript/README.md @@ -129,6 +129,15 @@ Generate a new idempotency key for each logical send. Keys remain bound to their `AgentIntercomAgentSession` manages registration, conservative lifecycle state, heartbeat, execution replacement, and shutdown cleanup for adapters that use the TypeScript client. +To use a shared file, download it whole instead of reading chunks yourself: + +```ts +const { attachment, data } = await reviewer.downloadAttachment(attachmentId) +console.log(attachment.name, data.byteLength) +``` + +`downloadAttachment` follows the chunk continuations (512 KiB per request), checks the attachment ID, offsets, size and SHA-256, and rejects an attachment over 16 MiB before reading it. `timeoutMs` applies to each chunk request, and an aborted `signal` stops it before the next chunk. It returns bytes and never writes to disk. `readAttachment` remains available for reading one chunk. + `pollInbox` provides an abortable async iterator over repeated bounded inbox waits. `withClaimedTask` releases a claim when work or completion fails. Use both with a live agent session so the execution lease remains current while work is claimed. ## Workspaces and connections diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json index 7572db1..3dcea4d 100644 --- a/sdk/typescript/package.json +++ b/sdk/typescript/package.json @@ -67,7 +67,7 @@ "prepack": "npm run build", "prepublishOnly": "node -e \"throw new Error('Publish the staged distribution through publish-npm-prerelease.yml, not this source directory')\"", "typecheck": "tsc --noEmit -p tsconfig.json", - "test:errors": "node test/errors.mjs && node --test test/sessions.mjs test/cli.mjs", + "test:errors": "node test/errors.mjs && node --test test/sessions.mjs test/cli.mjs test/attachments.mjs", "test:integration": "node test/integration.mjs", "test:release": "node ../../scripts/validate-launch.mjs --scripts-only", "validate:launch": "node ../../scripts/validate-launch.mjs", diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts index b238c35..ef89daa 100644 --- a/sdk/typescript/src/client.ts +++ b/sdk/typescript/src/client.ts @@ -59,6 +59,37 @@ export interface OperationOptions { timeoutMs?: number } +export interface DownloadedAttachment { + attachment: Attachment + /** The complete attachment, verified against its size and SHA-256. */ + data: Uint8Array +} + +const MAX_ATTACHMENT_BYTES = 16 * 1024 * 1024 +const MAX_ATTACHMENT_CHUNK_BYTES = 512 * 1024 + +function downloadFailure(reason: string): never { + throw new BusError('INTERNAL', `Attachment download failed: ${reason}`) +} + +function decodeBase64(value: unknown): Uint8Array { + if (typeof value !== 'string') downloadFailure('chunk data is missing') + let binary: string + try { + binary = atob(value) + } catch { + downloadFailure('chunk data is not valid base64') + } + const bytes = new Uint8Array(binary.length) + for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index) + return bytes +} + +async function sha256Hex(data: Uint8Array): Promise { + const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', data)) + return Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('') +} + export interface InboxReservationOptions extends OperationOptions { waitMs?: number } @@ -543,13 +574,52 @@ export class AgentIntercomClient { return request(this.address, this.agentToken, 'GET', `/v1/attachments?after=${encodeURIComponent(after)}&limit=${limit}`, undefined, options) } uploadAttachment(input: UploadAttachmentInput, data: Uint8Array, options?: OperationOptions): Promise { - if (data.byteLength > 16 * 1024 * 1024) throw new BusError('INVALID_ARGUMENT', 'Attachment exceeds 16 MiB') + if (data.byteLength > MAX_ATTACHMENT_BYTES) throw new BusError('INVALID_ARGUMENT', 'Attachment exceeds 16 MiB') const query = new URLSearchParams({ name: input.name, mediaType: input.mediaType ?? '', idempotencyKey: input.idempotencyKey ?? '' }) return request(this.address, this.agentToken, 'POST', `/v1/attachments?${query}`, new Blob([new Uint8Array(data)]), options) } readAttachment(id: string, offset = 0, limit = 65536, options?: OperationOptions): Promise { return request(this.address, this.agentToken, 'GET', `/v1/attachments/${encodeURIComponent(id)}?offset=${offset}&limit=${limit}`, undefined, options) } + /** + * Downloads a complete attachment in 512 KiB `readAttachment()` chunks (the server maximum) and verifies it: + * the same attachment ID, contiguous offsets, unchanged size and checksum, a + * continuation that advances exactly, the final byte count, and SHA-256. It + * refuses an attachment over 16 MiB before reading its bytes, and stops without + * requesting another chunk once `signal` is aborted. `timeoutMs` applies to each + * chunk request. Nothing is written to disk. + */ + async downloadAttachment(id: string, options?: OperationOptions): Promise { + let metadata: Attachment | undefined + let data: Uint8Array = new Uint8Array(0) + let offset = 0 + for (;;) { + // request() never sends once the signal is aborted, so cancellation stops + // the loop before another chunk is requested. + const chunk = await this.readAttachment(id, offset, MAX_ATTACHMENT_CHUNK_BYTES, options) + if (chunk.attachment?.id !== id || chunk.offset !== offset) downloadFailure('attachment ID or offset changed') + if (metadata === undefined) { + const { size, sha256 } = chunk.attachment + if (!Number.isSafeInteger(size) || size < 0 || size > MAX_ATTACHMENT_BYTES) { + downloadFailure('size is outside the 16 MiB attachment bound') + } + if (typeof sha256 !== 'string' || !/^[0-9a-f]{64}$/i.test(sha256)) downloadFailure('checksum is malformed') + metadata = chunk.attachment + data = new Uint8Array(size) + } else if (chunk.attachment.size !== metadata.size || chunk.attachment.sha256?.toLowerCase() !== metadata.sha256.toLowerCase()) { + downloadFailure('size or checksum changed during the download') + } + const bytes = decodeBase64(chunk.dataBase64) + if (offset + bytes.length > metadata.size) downloadFailure('received more bytes than the attachment size') + data.set(bytes, offset) + offset += bytes.length + if (chunk.nextOffset === undefined || chunk.nextOffset === null) break + if (bytes.length === 0 || chunk.nextOffset !== offset) downloadFailure('invalid continuation offset') + } + if (offset !== metadata.size) downloadFailure(`received ${offset} of ${metadata.size} bytes`) + if ((await sha256Hex(data)) !== metadata.sha256.toLowerCase()) downloadFailure('SHA-256 does not match') + return { attachment: metadata, data } + } async deleteAttachment(id: string, options?: OperationOptions): Promise { await request(this.address, this.agentToken, 'DELETE', `/v1/attachments/${encodeURIComponent(id)}`, undefined, options) } diff --git a/sdk/typescript/test/attachments.mjs b/sdk/typescript/test/attachments.mjs new file mode 100644 index 0000000..a64a359 --- /dev/null +++ b/sdk/typescript/test/attachments.mjs @@ -0,0 +1,142 @@ +import assert from 'node:assert/strict' +import { createHash, randomBytes } from 'node:crypto' +import { createServer } from 'node:http' +import { once } from 'node:events' +import { test } from 'node:test' +import { AgentIntercomClient, BusError } from '../dist/index.js' + +const ID = 'att_fixture' + +// Serves `bytes` in readAttachment chunks the way the Bus does. `alter` may +// rewrite a chunk to simulate a corrupted, truncated or inconsistent server. +async function fixture(bytes, alter = (chunk) => chunk, onRequest = () => {}) { + const attachment = { + id: ID, name: 'file.bin', mediaType: 'application/octet-stream', size: bytes.length, + sha256: createHash('sha256').update(bytes).digest('hex'), authorKind: 'agent', authorId: 'a', + createdAt: '2026-11-10T00:00:00Z', uri: `october-bus://attachments/${ID}` + } + const requests = [] + const server = createServer((request, response) => { + const url = new URL(request.url, 'http://fixture') + const offset = Number(url.searchParams.get('offset')) + const limit = Number(url.searchParams.get('limit')) + requests.push({ path: url.pathname, offset, limit }) + const data = bytes.subarray(offset, offset + limit) + const end = offset + data.length + const chunk = alter( + { attachment: { ...attachment }, offset, dataBase64: Buffer.from(data).toString('base64'), ...(end < bytes.length ? { nextOffset: end } : {}) }, + requests.length + ) + response.writeHead(200, { 'content-type': 'application/json' }) + response.end(JSON.stringify({ ok: true, result: chunk })) + onRequest(requests.length) + }) + server.listen(0, '127.0.0.1') + await once(server, 'listening') + const client = new AgentIntercomClient(`http://127.0.0.1:${server.address().port}`, 'token') + return { client, requests, attachment, close: () => server.close() } +} + +async function rejectsWith(promise, pattern) { + await assert.rejects(promise, (error) => error instanceof BusError && error.code === 'INTERNAL' && pattern.test(error.message)) +} + +test('downloads a file larger than one chunk and verifies it', async () => { + const bytes = randomBytes(1_200_000) + const { client, requests, attachment, close } = await fixture(bytes) + try { + const result = await client.downloadAttachment(ID) + assert.deepEqual(Buffer.from(result.data), bytes) + assert.equal(result.attachment.sha256, attachment.sha256) + assert.deepEqual(requests.map((r) => r.offset), [0, 524288, 1048576]) + assert(requests.every((r) => r.path === `/v1/attachments/${ID}` && r.limit === 524288)) + } finally { close() } +}) + +test('downloads a single-chunk file and an empty file', async () => { + const small = await fixture(Buffer.from('hello world')) + try { + const result = await small.client.downloadAttachment(ID) + assert.equal(Buffer.from(result.data).toString(), 'hello world') + assert.equal(small.requests.length, 1) + } finally { small.close() } + const empty = await fixture(Buffer.alloc(0)) + try { + assert.equal((await empty.client.downloadAttachment(ID)).data.length, 0) + } finally { empty.close() } +}) + +test('rejects corrupted content with an unchanged size', async () => { + const { client, close } = await fixture(randomBytes(600_000), (chunk, n) => { + if (n !== 2) return chunk + const data = Buffer.from(chunk.dataBase64, 'base64') + data[0] ^= 0xff + return { ...chunk, dataBase64: data.toString('base64') } + }) + try { await rejectsWith(client.downloadAttachment(ID), /SHA-256 does not match/) } finally { close() } +}) + +test('rejects truncated data', async () => { + const { client, close } = await fixture(randomBytes(600_000), (chunk) => { + const { nextOffset, ...rest } = chunk + return rest + }) + try { await rejectsWith(client.downloadAttachment(ID), /received 524288 of 600000 bytes/) } finally { close() } +}) + +test('rejects metadata that changes between chunks', async () => { + const cases = { + size: (a) => ({ ...a, size: a.size + 1 }), + checksum: (a) => ({ ...a, sha256: 'a'.repeat(64) }), + id: (a) => ({ ...a, id: 'att_other' }) + } + for (const [name, change] of Object.entries(cases)) { + const { client, close } = await fixture(randomBytes(600_000), (chunk, n) => (n === 2 ? { ...chunk, attachment: change(chunk.attachment) } : chunk)) + try { await rejectsWith(client.downloadAttachment(ID), /changed/) } catch (error) { throw new Error(`${name}: ${error.message}`) } finally { close() } + } +}) + +test('rejects bad offsets and continuations', async () => { + const cases = [ + [(chunk, n) => (n === 2 ? { ...chunk, offset: chunk.offset + 1 } : chunk), /ID or offset changed/], + [(chunk, n) => (n === 1 ? { ...chunk, nextOffset: chunk.nextOffset + 10 } : chunk), /invalid continuation/], + [(chunk, n) => (n === 1 ? { ...chunk, dataBase64: '', nextOffset: 0 } : chunk), /invalid continuation/], + [(chunk) => ({ ...chunk, dataBase64: Buffer.alloc(600_001).toString('base64') }), /more bytes than the attachment size/], + [(chunk) => ({ ...chunk, dataBase64: '***' }), /not valid base64/] + ] + for (const [alter, pattern] of cases) { + const { client, close } = await fixture(randomBytes(600_000), alter) + try { await rejectsWith(client.downloadAttachment(ID), pattern) } finally { close() } + } +}) + +test('refuses oversized or malformed metadata after one request', async () => { + for (const [change, pattern] of [ + [(a) => ({ ...a, size: 16 * 1024 * 1024 + 1 }), /outside the 16 MiB/], + [(a) => ({ ...a, size: -1 }), /outside the 16 MiB/], + [(a) => ({ ...a, sha256: 'not-a-checksum' }), /checksum is malformed/] + ]) { + const { client, requests, close } = await fixture(randomBytes(100_000), (chunk) => ({ ...chunk, attachment: change(chunk.attachment) })) + try { + await rejectsWith(client.downloadAttachment(ID), pattern) + assert.equal(requests.length, 1) + } finally { close() } + } +}) + +test('stops requesting chunks after cancellation', async () => { + const before = new AbortController() + before.abort(new Error('stopped early')) + const idle = await fixture(randomBytes(100_000)) + try { + await rejectsWith(idle.client.downloadAttachment(ID, { signal: before.signal }), /stopped early/) + assert.equal(idle.requests.length, 0) + } finally { idle.close() } + + const during = new AbortController() + const busy = await fixture(randomBytes(1_200_000), (chunk) => chunk, (n) => { if (n === 1) during.abort(new Error('stopped midway')) }) + try { + await rejectsWith(busy.client.downloadAttachment(ID, { signal: during.signal }), /stopped midway/) + assert.equal(busy.requests.length, 1) + } finally { busy.close() } +}) diff --git a/sdk/typescript/test/integration.mjs b/sdk/typescript/test/integration.mjs index 7f7a1d3..de945d0 100644 --- a/sdk/typescript/test/integration.mjs +++ b/sdk/typescript/test/integration.mjs @@ -124,6 +124,13 @@ try { const firstChunk = await reviewer.readAttachment(file.id, 0, 2) const secondChunk = await reviewer.readAttachment(file.id, firstChunk.nextOffset, 512) assert.deepEqual(Buffer.concat([Buffer.from(firstChunk.dataBase64, 'base64'), Buffer.from(secondChunk.dataBase64, 'base64')]), Buffer.from(fileBytes)) + const downloaded = await reviewer.downloadAttachment(file.id) + assert.deepEqual(Buffer.from(downloaded.data), Buffer.from(fileBytes)) + assert.equal(downloaded.attachment.sha256, file.sha256) + const largeBytes = new Uint8Array(600 * 1024).map((_, index) => (index * 31) % 251) + const large = await planner.uploadAttachment({ name: 'large.bin', idempotencyKey: 'sdk-large-file' }, largeBytes) + assert.deepEqual(Buffer.from((await reviewer.downloadAttachment(large.id)).data), Buffer.from(largeBytes)) + await planner.deleteAttachment(large.id) await assert.rejects(reviewer.deleteAttachment(file.id), error => error.code === 'PERMISSION_DENIED') await planner.deleteAttachment(file.id) await assert.rejects(reviewer.readAttachment(file.id), error => error.code === 'NOT_FOUND')