Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions sdk/typescript/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion sdk/typescript/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
72 changes: 71 additions & 1 deletion sdk/typescript/src/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<ArrayBuffer>): Promise<string> {
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
}
Expand Down Expand Up @@ -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<Attachment> {
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<AttachmentContent> {
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<DownloadedAttachment> {
let metadata: Attachment | undefined
let data: Uint8Array<ArrayBuffer> = 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<void> {
await request(this.address, this.agentToken, 'DELETE', `/v1/attachments/${encodeURIComponent(id)}`, undefined, options)
}
Expand Down
142 changes: 142 additions & 0 deletions sdk/typescript/test/attachments.mjs
Original file line number Diff line number Diff line change
@@ -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() }
})
7 changes: 7 additions & 0 deletions sdk/typescript/test/integration.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand Down
Loading