Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript

feat: localize BYOA attachments and image inputs (#361)

Strelizia3b77551100dd
diff --git a/server/src/__tests__/agents-computer-attachment-cache.test.ts b/server/src/__tests__/agents-computer-attachment-cache.test.ts
new file mode 100644
index 0000000..cff17fd
--- /dev/null
+++ b/server/src/__tests__/agents-computer-attachment-cache.test.ts
@@ -0,0 +1,176 @@
+import assert from 'node:assert/strict'
+import { mkdir, mkdtemp, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import test from 'node:test'
+
+import { AgentAttachmentCache, renderCachedAttachments } from '../agents/computer/attachment-cache.js'
+
+test('each attachment is downloaded through the runtime endpoint into agent home', async () => {
+ const home = await mkdtemp(join(tmpdir(), 'cumora-attachment-cache-'))
+ const requests: Array<{ url: string; authorization: string | null }> = []
+ const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+ const url = String(input)
+ requests.push({ url, authorization: new Headers(init?.headers).get('authorization') })
+ assert.match(url, /\/runtime\/attachment\?key=attachments%2F.*messageId=message-1/)
+ return new Response('hello from attachment', {
+ status: 200,
+ headers: { 'content-type': 'text/plain', 'content-length': '21' },
+ })
+ }) as typeof fetch
+ try {
+ const cache = new AgentAttachmentCache(home, 'https://cumora.example', async () => 'runtime-token', fetchImpl)
+ const result = await cache.materialize('message-1', [
+ { name: '../secret.txt', kind: 'file', key: 'attachments/a.txt', mime: 'text/plain', size: 21 },
+ { name: 'image.png', kind: 'img', key: 'attachments/b.png', mime: 'image/png', size: 21 },
+ ])
+ assert.equal(result.files.length, 2)
+ assert.equal(requests.length, 2)
+ assert.ok(requests.every((request) => request.authorization === 'Bearer runtime-token'))
+ assert.equal(result.files[0].text, 'hello from attachment')
+ assert.ok(result.files.every((file) => file.path.startsWith(join(home, 'attachments', 'message-1'))))
+ assert.equal(await readFile(result.files[0].path, 'utf8'), 'hello from attachment')
+ if (process.platform !== 'win32') assert.equal((await stat(result.files[0].path)).mode & 0o777, 0o600)
+ const rendered = renderCachedAttachments(result, 'unsupported')
+ assert.match(rendered, /File excerpt/)
+ assert.match(rendered, /does not support image input/)
+ assert.match(rendered, /Do not claim to have seen/)
+ } finally {
+ await rm(home, { recursive: true, force: true })
+ }
+})
+
+test('non-Cumora keys and download failures are reported without escaping agent home', async () => {
+ const home = await mkdtemp(join(tmpdir(), 'cumora-attachment-cache-'))
+ const fetchImpl = (async () => new Response('too large?', { status: 500 })) as typeof fetch
+ try {
+ const cache = new AgentAttachmentCache(home, 'https://cumora.example', async () => 'token', fetchImpl)
+ const result = await cache.materialize('../../outside', [
+ { name: 'external.txt', kind: 'file', url: 'https://example.com/a.txt' },
+ { name: 'failed.txt', kind: 'file', key: 'attachments/failed.txt' },
+ ])
+ assert.equal(result.files.length, 0)
+ assert.equal(result.failures.length, 2)
+ assert.match(result.failures[0].reason, /trusted Cumora attachment key/)
+ assert.match(result.failures[1].reason, /HTTP 500/)
+ assert.match(renderCachedAttachments(result, 'unknown'), /could not be downloaded/)
+ } finally {
+ await rm(home, { recursive: true, force: true })
+ }
+})
+
+test('text excerpts stop at 50 KiB and remain available as local files', async () => {
+ const home = await mkdtemp(join(tmpdir(), 'cumora-attachment-cache-'))
+ const body = Buffer.alloc(50 * 1024 + 7, 'a')
+ const fetchImpl = (async () => new Response(body, {
+ status: 200,
+ headers: { 'content-type': 'text/plain', 'content-length': String(body.length) },
+ })) as typeof fetch
+ try {
+ const cache = new AgentAttachmentCache(home, 'https://cumora.example', async () => 'token', fetchImpl)
+ const result = await cache.materialize('message-large', [
+ { name: 'large.txt', kind: 'file', key: 'attachments/large.txt', mime: 'text/plain', size: body.length },
+ ])
+ assert.equal(result.files.length, 1)
+ assert.equal(Buffer.byteLength(result.files[0].text ?? ''), 50 * 1024)
+ assert.equal(result.files[0].textTruncated, true)
+ assert.equal((await readFile(result.files[0].path)).length, body.length)
+ } finally {
+ await rm(home, { recursive: true, force: true })
+ }
+})
+
+test('cache directories cannot be redirected through a pre-existing file', async () => {
+ const home = await mkdtemp(join(tmpdir(), 'cumora-attachment-cache-'))
+ await writeFile(join(home, 'attachments'), 'not a directory')
+ try {
+ const cache = new AgentAttachmentCache(home, 'https://cumora.example', async () => 'token')
+ await assert.rejects(
+ cache.materialize('message-1', [{ name: 'a.txt', kind: 'file', key: 'attachments/a.txt' }]),
+ /not a private directory/,
+ )
+ } finally {
+ await rm(home, { recursive: true, force: true })
+ }
+})
+
+test('declared oversized downloads fail before the response body is stored', async () => {
+ const home = await mkdtemp(join(tmpdir(), 'cumora-attachment-cache-'))
+ const fetchImpl = (async () => new Response('small', {
+ status: 200,
+ headers: { 'content-length': String(25 * 1024 * 1024 + 1) },
+ })) as typeof fetch
+ try {
+ const cache = new AgentAttachmentCache(home, 'https://cumora.example', async () => 'token', fetchImpl)
+ const result = await cache.materialize('message-1', [
+ { name: 'too-large.bin', kind: 'file', key: 'attachments/too-large.bin' },
+ ])
+ assert.equal(result.files.length, 0)
+ assert.match(result.failures[0].reason, /25 MiB/)
+ } finally {
+ await rm(home, { recursive: true, force: true })
+ }
+})
+
+test('cleanup expires old files and protects paths used by the current turn', async () => {
+ const home = await mkdtemp(join(tmpdir(), 'cumora-attachment-cache-'))
+ try {
+ const fetchImpl = (async () => new Response('live', {
+ status: 200,
+ headers: { 'content-length': '4', 'content-type': 'text/plain' },
+ })) as typeof fetch
+ const cache = new AgentAttachmentCache(home, 'https://cumora.example', async () => 'token', fetchImpl, {
+ maxAgeMs: 60_000,
+ maxBytes: 1024,
+ now: () => 120_000,
+ })
+ cache.beginTurn()
+ const liveResult = await cache.materialize('live-message', [{
+ name: 'live.txt', kind: 'file', key: 'attachments/live.txt', mime: 'text/plain',
+ }])
+ const liveFile = liveResult.files[0]?.path
+ assert.ok(liveFile)
+ const oldDir = join(home, 'attachments', 'old-message')
+ await mkdir(oldDir, { recursive: true })
+ const oldFile = join(oldDir, 'old.txt')
+ await writeFile(oldFile, 'old')
+ await utimes(oldFile, new Date(0), new Date(0))
+ const result = await cache.cleanup()
+ assert.equal(result.removedFiles, 1)
+ await assert.rejects(stat(oldFile))
+ assert.equal(await readFile(liveFile, 'utf8'), 'live')
+ await cache.endTurn()
+ await cache.dispose()
+ assert.equal(await readFile(liveFile, 'utf8'), 'live')
+ await cache.dispose({ purge: true })
+ await assert.rejects(stat(liveFile))
+ } finally {
+ await rm(home, { recursive: true, force: true })
+ }
+})
+
+test('cleanup evicts least recently used files over the per-agent byte cap', async () => {
+ const home = await mkdtemp(join(tmpdir(), 'cumora-attachment-cache-'))
+ try {
+ const cache = new AgentAttachmentCache(home, 'https://cumora.example', async () => 'token', fetch, {
+ maxAgeMs: 24 * 60 * 60 * 1000,
+ maxBytes: 5,
+ now: () => 10_000,
+ })
+ const { mkdir } = await import('node:fs/promises')
+ const dir = join(home, 'attachments', 'message')
+ await mkdir(dir, { recursive: true })
+ const leastRecent = join(dir, 'least.txt')
+ const recent = join(dir, 'recent.txt')
+ await writeFile(leastRecent, '1234')
+ await writeFile(recent, '5678')
+ await utimes(leastRecent, new Date(1_000), new Date(1_000))
+ await utimes(recent, new Date(9_000), new Date(9_000))
+ const result = await cache.cleanup()
+ assert.equal(result.removedFiles, 1)
+ await assert.rejects(stat(leastRecent))
+ assert.equal(await readFile(recent, 'utf8'), '5678')
+ } finally {
+ await rm(home, { recursive: true, force: true })
+ }
+})
diff --git a/server/src/__tests__/agents-computer-attachment-visibility.test.ts b/server/src/__tests__/agents-computer-attachment-visibility.test.ts
index 609efee..51e6d65 100644
--- a/server/src/__tests__/agents-computer-attachment-visibility.test.ts
+++ b/server/src/__tests__/agents-computer-attachment-visibility.test.ts
@@ -16,7 +16,7 @@ import assert from 'node:assert/strict'
process.env.CUMORA_RUNTIME_CLIENT = 'http'
process.env.OPENAI_API_KEY ??= 'test-key'
-const { attachmentNote } = await import('../agents/computer/daemon.js')
+const { attachmentNote, attachmentNotes } = await import('../agents/computer/daemon.js')
test('the reported zip is now visible to the agent', () => {
const note = attachmentNote({
@@ -57,3 +57,16 @@ test('hostile fields cannot run away with the digest line', () => {
assert.equal(note.includes('file:///etc/passwd'), false, 'only http(s) urls are surfaced')
assert.equal(note.includes('NaN'), false)
})
+
+test('the inbox digest does not expose signed attachment URLs', () => {
+ const notes = attachmentNotes([{
+ name: 'data.csv',
+ kind: 'file',
+ mime: 'text/csv',
+ size: 12,
+ url: 'https://cdn.cumora.ai/a/abc?sig=secret',
+ }])
+ assert.match(notes, /data\.csv/)
+ assert.equal(notes.includes('cdn.cumora.ai'), false)
+ assert.equal(notes.includes('sig=secret'), false)
+})
diff --git a/server/src/__tests__/agents-computer-doctor-verdict.test.ts b/server/src/__tests__/agents-computer-doctor-verdict.test.ts
index 6a5176a..14cc5e4 100644
--- a/server/src/__tests__/agents-computer-doctor-verdict.test.ts
+++ b/server/src/__tests__/agents-computer-doctor-verdict.test.ts
@@ -61,8 +61,8 @@ test('the verdict is drawn from the gate-aware helper, not from brains alone', a
// The four tests above exercise the helper. They would all still pass against
// a runDoctor that computed its own verdict and never called it — which is
// exactly the state being fixed. Read the source.
- const source = await readFile(new URL('../agents/computer/daemon.ts', import.meta.url), 'utf8')
- const doctor = source.slice(source.indexOf('async function runDoctor'))
+ const source = (await readFile(new URL('../agents/computer/daemon.ts', import.meta.url), 'utf8')).replaceAll('\r\n', '\n')
+ const doctor = source.slice(source.indexOf('async function runDoctor('))
const body = doctor.slice(0, doctor.indexOf('\n}\n') + 2)
assert.match(body, /doctorUsableEngines\(/, 'runDoctor no longer asks the gate')
diff --git a/server/src/__tests__/agents-computer-engine.test.ts b/server/src/__tests__/agents-computer-engine.test.ts
index 20d0825..6f16fdb 100644
--- a/server/src/__tests__/agents-computer-engine.test.ts
+++ b/server/src/__tests__/agents-computer-engine.test.ts
@@ -585,7 +585,7 @@ test('grok adapter seeds AGENTS.md and reports sessionId from stream-json', asyn
signal: new AbortController().signal,
})
- assert.equal(result.exitCode, 0)
+ assert.equal(result.exitCode, 0, `grok fixture failed: ${result.error ?? 'no error text'}`)
assert.equal(result.sessionId, 'sess-grok-1')
assert.equal(result.model, 'grok-4.6')
})
@@ -641,10 +641,21 @@ test('Codex one-shot paths send prompts through stdin', async () => {
await mkdir(home)
const capture = join(binDir, 'capture.js')
- const captureSource = "let stdin = ''\n" +
- "process.stdin.setEncoding('utf8')\n" +
- "process.stdin.on('data', (chunk) => { stdin += chunk })\n" +
- "process.stdin.on('end', () => process.stdout.write(JSON.stringify({ argv: process.argv.slice(2), stdin })))\n"
+ const captureSource = "const readline = require('node:readline')\n" +
+ "const appServer = process.argv.includes('app-server')\n" +
+ "if (appServer) {\n" +
+ " const send = (message) => process.stdout.write(JSON.stringify(message) + '\\n')\n" +
+ " readline.createInterface({ input: process.stdin }).on('line', (line) => {\n" +
+ " const message = JSON.parse(line)\n" +
+ " if (message.id === 1) send({ id: 1, result: {} })\n" +
+ " if (message.id === 2) send({ id: 2, result: { config: {} } })\n" +
+ " })\n" +
+ "} else {\n" +
+ " let stdin = ''\n" +
+ " process.stdin.setEncoding('utf8')\n" +
+ " process.stdin.on('data', (chunk) => { stdin += chunk })\n" +
+ " process.stdin.on('end', () => process.stdout.write(JSON.stringify({ argv: process.argv.slice(2), stdin }) + '\\n'))\n" +
+ "}\n"
await writeFile(capture, captureSource, 'utf8')
if (IS_WIN) {
// Mirror npm's standard layout. Cumora must invoke this JS entry point
@@ -749,6 +760,112 @@ test('Codex one-shot paths send prompts through stdin', async () => {
assert.equal(probeCapture.stdin, 'Connectivity check. Reply with exactly: OK')
})
+test('Codex persistent turns preserve queued native image input', { skip: IS_WIN, timeout: 5000 }, async () => {
+ const source = `
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + '\\n')
+const log = (msg) => process.stderr.write(JSON.stringify(msg) + '\\n')
+require('node:readline').createInterface({ input: process.stdin }).on('line', line => {
+ const msg = JSON.parse(line)
+ if (msg.method === 'initialize') send({ id: msg.id, result: {} })
+ if (msg.method === 'thread/start') send({ id: msg.id, result: { thread: { id: 'fixture-thread' } } })
+ if (msg.method === 'turn/start') {
+ log(msg)
+ send({ id: msg.id, result: { turn: { id: 'fixture-turn' } } })
+ send({ method: 'turn/completed', params: { turn: { id: 'fixture-turn', status: 'completed' } } })
+ }
+})`
+
+ for (const vision of ['supported', 'unknown', 'unsupported'] as const) {
+ const { session, logs, home } = await startFakeCodexSession({ vision, source })
+ const image = join(home, 'attachments', 'diagram.png')
+ const outsideImage = join(dirname(home), 'outside.png')
+ await mkdir(dirname(image), { recursive: true })
+ await writeFile(image, 'image fixture', 'utf8')
+ await writeFile(outsideImage, 'outside fixture', 'utf8')
+
+ const result = await session.send('describe the image', [image, image, 'relative.png', outsideImage])
+ assert.equal(result.exitCode, 0)
+ const turn = logs
+ .filter((line) => line.startsWith('{'))
+ .map((line) => JSON.parse(line) as { method?: string; params?: { input?: unknown } })
+ .find((request) => request.method === 'turn/start')
+ assert.deepEqual(turn?.params?.input, [
+ { type: 'text', text: 'describe the image', text_elements: [] },
+ ...(vision === 'supported' ? [{ type: 'localImage', path: image }] : []),
+ ])
+ }
+})
+
+test('Codex one-shot image arguments preserve fresh and resumed command shapes', async () => {
+ const root = await mkdtemp(join(tmpdir(), 'cumora-codex-images-exec-'))
+ tempDirs.push(root)
+ const binDir = join(root, 'bin')
+ const home = join(root, 'home')
+ const image = join(home, 'attachments', 'diagram.png')
+ const outsideImage = join(root, 'outside.png')
+ await mkdir(join(home, 'attachments'), { recursive: true })
+ await mkdir(binDir)
+ await writeFile(image, 'image fixture', 'utf8')
+ await writeFile(outsideImage, 'outside fixture', 'utf8')
+ await writeFakeCli(binDir, 'codex', `
+const readline = require('node:readline')
+const appServer = process.argv.includes('app-server')
+if (appServer) {
+ const send = message => process.stdout.write(JSON.stringify(message) + '\\n')
+ readline.createInterface({ input: process.stdin }).on('line', line => {
+ const message = JSON.parse(line)
+ if (message.id === 1) send({ id: 1, result: {} })
+ if (message.id === 2) send({ id: 2, result: { config: {} } })
+ })
+} else {
+ let stdin = ''
+ process.stdin.setEncoding('utf8')
+ process.stdin.on('data', chunk => { stdin += chunk })
+ process.stdin.on('end', () => process.stdout.write(JSON.stringify({ argv: process.argv.slice(2), stdin }) + '\\n'))
+}`)
+ useFakeCliPath(binDir)
+ process.env.CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'
+
+ const run = async (resumeSessionId: string | undefined, vision: 'supported' | 'unsupported' | 'unknown') => {
+ const logs: string[] = []
+ const result = await getAdapter('codex').run({
+ home,
+ prompt: 'describe the image',
+ env: secureClaudeEnv(root),
+ model: null,
+ fastModel: null,
+ resumeSessionId,
+ vision,
+ localImages: [image, image, 'relative.png', outsideImage],
+ onLog: (line) => logs.push(line),
+ signal: new AbortController().signal,
+ })
+ assert.equal(result.exitCode, 0)
+ return JSON.parse(logs.at(-1) ?? '{}') as { argv?: string[]; stdin?: string }
+ }
+
+ const fresh = await run(undefined, 'supported')
+ assert.equal(fresh.stdin, 'describe the image')
+ assert.equal(fresh.argv?.filter((arg) => arg === '--image').length, 1)
+ const freshImage = fresh.argv?.indexOf('--image') ?? -1
+ assert.equal(fresh.argv?.[freshImage + 1], image)
+ assert.equal(fresh.argv?.includes('resume'), false)
+
+ const resumed = await run('fixture-thread', 'supported')
+ const resumeIndex = resumed.argv?.indexOf('resume') ?? -1
+ const resumedImage = resumed.argv?.indexOf('--image') ?? -1
+ const threadIndex = resumed.argv?.indexOf('fixture-thread') ?? -1
+ assert.ok(resumeIndex >= 0)
+ assert.ok(resumedImage > resumeIndex)
+ assert.equal(resumed.argv?.[resumedImage + 1], image)
+ assert.ok(threadIndex > resumedImage)
+
+ for (const vision of ['unknown', 'unsupported'] as const) {
+ const capture = await run(undefined, vision)
+ assert.equal(capture.argv?.includes('--image'), false, `${vision} capability must not send native image input`)
+ }
+})
+
test('Claude and Codex one-shot adapters return structured engine failures', async () => {
const root = await mkdtemp(join(tmpdir(), 'cumora-structured-engine-failures-'))
tempDirs.push(root)
@@ -757,7 +874,17 @@ test('Claude and Codex one-shot adapters return structured engine failures', asy
await mkdir(binDir)
await mkdir(home)
await writeFakeCli(binDir, 'claude', "process.stderr.write('No conversation found with session ID: claude-stale\\n')\nprocess.exit(1)\n")
- await writeFakeCli(binDir, 'codex', "process.stderr.write('429 Too Many Requests: rate limit reached\\n')\nprocess.exit(1)\n")
+ await writeFakeCli(binDir, 'codex', `
+if (process.argv.includes('app-server')) {
+ require('node:readline').createInterface({ input: process.stdin }).on('line', line => {
+ const message = JSON.parse(line)
+ if (message.id === 1) process.stdout.write(JSON.stringify({ id: 1, result: {} }) + '\\n')
+ if (message.id === 2) process.stdout.write(JSON.stringify({ id: 2, result: { config: {} } }) + '\\n')
+ })
+} else {
+ process.stderr.write('429 Too Many Requests: rate limit reached\\n')
+ process.exit(1)
+}`)
useFakeCliPath(binDir)
process.env.CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'
@@ -831,7 +958,7 @@ async function fakeCodexRejectingThread(root: string): Promise<string> {
return binDir
}
-async function startFakeCodexSession(opts: { resume?: string; source?: string; onLog?: (line: string) => void } = {}) {
+async function startFakeCodexSession(opts: { resume?: string; source?: string; vision?: 'supported' | 'unsupported' | 'unknown'; onLog?: (line: string) => void } = {}) {
process.env.CUMORA_BYOA_ALLOW_UNSANDBOXED = '1'
const root = await mkdtemp(join(tmpdir(), 'cumora-codex-'))
tempDirs.push(root)
@@ -850,11 +977,12 @@ async function startFakeCodexSession(opts: { resume?: string; source?: string; o
home,
env: secureClaudeEnv(root),
resumeSessionId: opts.resume ?? null,
+ vision: opts.vision,
onLog: (l) => { logs.push(l); opts.onLog?.(l) },
})
assert.ok(session, 'codex adapter must start a persistent session on this platform')
liveSessions.push(session!)
- return { session: session!, logs }
+ return { session: session!, logs, home }
}
const BWRAP_STARTUP_ERROR = 'bwrap: execvp /missing/codex: No such file or directory'
diff --git a/server/src/__tests__/agents-computer-inbox-digest.test.ts b/server/src/__tests__/agents-computer-inbox-digest.test.ts
index f69171a..61b74c6 100644
--- a/server/src/__tests__/agents-computer-inbox-digest.test.ts
+++ b/server/src/__tests__/agents-computer-inbox-digest.test.ts
@@ -13,7 +13,7 @@
*/
import { test } from 'node:test'
import assert from 'node:assert/strict'
-import { conversationHeader, renderInboxDigest } from '../agents/computer/daemon.js'
+import { conversationHeader, renderInboxDigest, visibleInboxMessageIds } from '../agents/computer/daemon.js'
type Convo = { head: string; msgs: string[] }
@@ -78,6 +78,26 @@ test('the budget is respected', () => {
assert.ok(messageLines(digest).length <= 40, 'must not exceed the line budget')
})
+test('attachment materialization follows the messages the digest actually shows', () => {
+ const byConvo = new Map([
+ ['dm', {
+ head: '# dm',
+ msgs: [' [dm-0] dm: one'],
+ ids: ['dm-0'],
+ }],
+ ['busy', {
+ head: '# busy',
+ msgs: Array.from({ length: 60 }, (_, i) => ` [busy-${i}] busy: ${i}`),
+ ids: Array.from({ length: 60 }, (_, i) => `busy-${i}`),
+ }],
+ ])
+ const visible = visibleInboxMessageIds(byConvo, 40)
+ assert.ok(visible.has('dm-0'))
+ assert.ok(visible.has('busy-59'))
+ assert.ok(!visible.has('busy-0'), 'older unread rows outside the digest are not downloaded')
+ assert.equal(visible.size, 40)
+})
+
test('a conversation budgeted to zero shows none of its messages, not all of them', () => {
// Guards the slice(length - shown) vs slice(-shown) trap: slice(-0) is
// slice(0), which would dump the whole conversation.
diff --git a/server/src/__tests__/agents-computer-model-capabilities.test.ts b/server/src/__tests__/agents-computer-model-capabilities.test.ts
new file mode 100644
index 0000000..cc6c108
--- /dev/null
+++ b/server/src/__tests__/agents-computer-model-capabilities.test.ts
@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import {
+ engineCapabilities,
+ visionCapabilityForModel,
+ type VisionCapability,
+} from '../agents/computer/model-capabilities.js'
+
+test('missing or untrusted model capability remains unknown', () => {
+ assert.equal(visionCapabilityForModel({ models: [{ id: 'custom', label: 'custom' }] }, 'custom'), 'unknown')
+ assert.equal(visionCapabilityForModel(null, 'custom'), 'unknown')
+ assert.equal(visionCapabilityForModel({ models: [{ id: 'custom', label: 'custom', vision: 'unsupported' }] }, 'custom'), 'unsupported')
+})
+
+test('explicit model capability wins without guessing from the vendor name', () => {
+ const capabilities: VisionCapability[] = ['supported', 'unsupported', 'unknown']
+ for (const vision of capabilities) {
+ assert.equal(visionCapabilityForModel({ models: [{ id: 'gpt-vision', label: 'gpt-vision', vision }] }, 'gpt-vision'), vision)
+ }
+ assert.equal(visionCapabilityForModel({ models: [{ id: 'gpt-vision', label: 'gpt-vision' }] }, 'gpt-vision'), 'unknown')
+})
+
+test('attachment access is daemon-mediated in both filesystem modes', () => {
+ assert.deepEqual(engineCapabilities('claude'), {
+ engine: 'claude', filesystem: 'sandboxed', attachmentAccess: 'daemon-cache', vision: 'unknown',
+ })
+ assert.deepEqual(engineCapabilities('cursor', { unsandboxed: true, vision: 'supported' }), {
+ engine: 'cursor', filesystem: 'compatibility', attachmentAccess: 'daemon-cache', vision: 'supported',
+ })
+})
diff --git a/server/src/__tests__/agents-computer-runtime-cli-attachments.test.ts b/server/src/__tests__/agents-computer-runtime-cli-attachments.test.ts
new file mode 100644
index 0000000..94b2fa9
--- /dev/null
+++ b/server/src/__tests__/agents-computer-runtime-cli-attachments.test.ts
@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+process.env.CUMORA_RUNTIME_CLIENT = 'http'
+process.env.OPENAI_API_KEY ??= 'test-key'
+
+const { enrichCliJsonWithAttachmentPaths } = await import('../agents/computer/daemon.js')
+
+test('runtime CLI JSON exposes cached paths and text for every attachment', () => {
+ const attachment = { name: 'notes.txt', kind: 'file' as const, key: 'attachments/notes.txt', mime: 'text/plain' }
+ const image = { name: 'diagram.png', kind: 'img' as const, key: 'attachments/diagram.png', mime: 'image/png' }
+ const failed = { name: 'missing.png', kind: 'img' as const, key: 'attachments/missing.png', mime: 'image/png' }
+ const cached = {
+ files: [
+ {
+ attachment,
+ path: '/agent/home/attachments/message-1/1-a.txt',
+ text: 'inline content',
+ textTruncated: false,
+ },
+ {
+ attachment: image,
+ path: '/agent/home/attachments/message-1/2-a.png',
+ },
+ ],
+ failures: [{ name: 'missing.png', key: 'attachments/missing.png', reason: 'HTTP 404' }],
+ }
+ const enriched = enrichCliJsonWithAttachmentPaths(
+ JSON.stringify([{ id: 'message-1', body: 'see file', attachments: [attachment, image, failed], attachment }]),
+ new Map([['message-1', cached]]),
+ 'unknown',
+ )
+ assert.ok(enriched)
+ const rows = JSON.parse(enriched) as Array<Record<string, unknown>>
+ const attachments = rows[0].attachments as Array<Record<string, unknown>>
+ for (const descriptor of [
+ attachments[0],
+ rows[0].attachment as Record<string, unknown>,
+ ]) {
+ assert.equal(descriptor.localPath, '/agent/home/attachments/message-1/1-a.txt')
+ assert.equal(descriptor.localText, 'inline content')
+ assert.equal(descriptor.localTextTruncated, false)
+ }
+ assert.equal(attachments[1].localPath, '/agent/home/attachments/message-1/2-a.png')
+ assert.match(String(attachments[1].localImageGuidance), /Do not claim to have seen it/)
+ assert.equal(attachments[2].localPath, undefined)
+ assert.equal(attachments[2].localError, 'HTTP 404')
+})
+
+test('non-JSON CLI text is left for the caller to append cache guidance', () => {
+ assert.equal(enrichCliJsonWithAttachmentPaths('plain output', new Map(), 'unknown'), null)
+})
diff --git a/server/src/__tests__/agents-runtime-attachment-authorization.test.ts b/server/src/__tests__/agents-runtime-attachment-authorization.test.ts
new file mode 100644
index 0000000..a3015c0
--- /dev/null
+++ b/server/src/__tests__/agents-runtime-attachment-authorization.test.ts
@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+process.env.OPENAI_API_KEY ??= 'test-key'
+
+const { attachmentUrlMatchesStorageKey } = await import('../agents/runtime/authorization.js')
+
+test('legacy local attachment URLs authorize the exact derived key', () => {
+ assert.equal(
+ attachmentUrlMatchesStorageKey('/uploads/attachments/report.pdf?download=1', 'attachments/report.pdf'),
+ true,
+ )
+})
+
+test('arbitrary public URLs never authorize a chat storage key', () => {
+ assert.equal(
+ attachmentUrlMatchesStorageKey('https://example.com/attachments/report.pdf', 'attachments/report.pdf'),
+ false,
+ )
+})
+
+test('a key-looking URL path cannot substitute for the requested object', () => {
+ assert.equal(
+ attachmentUrlMatchesStorageKey('/uploads/attachments/report.pdf', 'attachments/other.pdf'),
+ false,
+ )
+})
diff --git a/server/src/__tests__/attachment-input-parts.test.ts b/server/src/__tests__/attachment-input-parts.test.ts
new file mode 100644
index 0000000..94251ca
--- /dev/null
+++ b/server/src/__tests__/attachment-input-parts.test.ts
@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import type { AttachmentDescriptor } from '../../../shared/attachments.js'
+import {
+ attachmentInputParts,
+ textExcerptPart,
+ type VisionCapability,
+} from '../attachments/input-parts.js'
+
+const image: AttachmentDescriptor = {
+ name: 'diagram.png',
+ kind: 'img',
+ mime: 'image/png',
+ url: 'data:image/png;base64,c2FmZQ==',
+}
+
+test('a supported vision model receives a label and image part', () => {
+ assert.deepEqual(attachmentInputParts([image], { vision: 'supported', messageId: 'm1' }), [
+ { type: 'text', text: 'Image attached to message m1 ("diagram.png"):' },
+ { type: 'image', imageUrl: image.url, detail: 'auto' },
+ ])
+})
+
+test('a legacy single descriptor is accepted at the part-builder boundary', () => {
+ assert.deepEqual(attachmentInputParts(image, { vision: 'supported', messageId: 'legacy' }), [
+ { type: 'text', text: 'Image attached to message legacy ("diagram.png"):' },
+ { type: 'image', imageUrl: image.url, detail: 'auto' },
+ ])
+})
+
+test('unsupported and unknown vision produce distinct unreadable-image notices', () => {
+ const parts = (vision: VisionCapability) => attachmentInputParts([image], { vision, messageId: 'm2' })
+ const unsupported = parts('unsupported')[1]
+ const unknown = parts('unknown')[1]
+ assert.equal(unsupported.type, 'unreadable-image')
+ assert.equal(unknown.type, 'unreadable-image')
+ if (unsupported.type !== 'unreadable-image' || unknown.type !== 'unreadable-image') return
+ assert.match(unsupported.text, /does not support image input/)
+ assert.match(unknown.text, /support is unknown/)
+ assert.doesNotMatch(unsupported.text, /support is unknown/)
+})
+
+test('a supported model still gets a notice when the image bytes are unavailable', () => {
+ const parts = attachmentInputParts([{
+ name: 'missing.png',
+ kind: 'img',
+ key: 'attachments/missing.png',
+ }], {
+ vision: 'supported',
+ messageId: 'm3',
+ })
+ assert.deepEqual(parts, [
+ { type: 'text', text: 'Image attached to message m3 ("missing.png"):' },
+ {
+ type: 'unreadable-image',
+ text: 'Image "missing.png" was not included: the image data is unavailable. Its metadata is still available; do not claim to have seen it.',
+ },
+ ])
+})
+
+test('non-image attachments produce no image parts', () => {
+ assert.deepEqual(attachmentInputParts([
+ { name: 'notes.txt', kind: 'file', mime: 'text/plain' },
+ { name: 'brief.pdf', kind: 'pdf' },
+ ], { vision: 'supported', messageId: 'm4' }), [])
+})
+
+test('text excerpts are capped at 50 KiB and replace invalid UTF-8', () => {
+ const source = new Uint8Array(50 * 1024 + 4)
+ source.fill(0x61)
+ source.set([0xff, 0xfe, 0xfd, 0xfc], 50 * 1024)
+ const part = textExcerptPart({ name: 'notes.txt', kind: 'file', mime: 'text/plain' }, source)
+ assert.equal(part.type, 'text')
+ if (part.type !== 'text') return
+ assert.match(part.text, /^File excerpt \("notes.txt"\):\n/)
+ assert.ok(part.text.endsWith('a'))
+ assert.ok(new TextEncoder().encode(part.text).length < 50 * 1024 + 100)
+})
diff --git a/server/src/__tests__/electron-native-image.test.ts b/server/src/__tests__/electron-native-image.test.ts
index e93d689..6155512 100644
--- a/server/src/__tests__/electron-native-image.test.ts
+++ b/server/src/__tests__/electron-native-image.test.ts
@@ -55,8 +55,7 @@ test('the dock unread icon is built from a bitmap', () => {
// The positive half: it is not enough that the SVG is gone, the dot must
// actually be composited into the icon.
const src = readFileSync(MAIN_CJS, 'utf8')
- const fn = src.slice(src.indexOf('function getDockUnreadIcon'))
- const body = fn.slice(0, fn.indexOf('\n}\n') + 3)
+ const body = src.match(/function getDockUnreadIcon\(\)\s*\{([\s\S]*?)\r?\n\}/)?.[1] ?? ''
assert.match(body, /createFromBitmap/, 'getDockUnreadIcon must composite via a raw bitmap')
})
diff --git a/server/src/agents/cli-result.ts b/server/src/agents/cli-result.ts
index 455a92d..f6fcfa2 100644
--- a/server/src/agents/cli-result.ts
+++ b/server/src/agents/cli-result.ts
@@ -1,3 +1,5 @@
+import type { AttachmentDescriptor } from '../../../shared/attachments.js'
+
export interface CliSideEffect {
event: string
command?: string
@@ -9,11 +11,21 @@ export interface CliSideEffect {
[key: string]: unknown
}
+/** Attachment descriptors discovered by a read command. The runtime HTTP
+ * surface returns these beside the rendered text so a BYOA daemon can cache
+ * the exact files the agent just inspected. They never choose a fetch URL:
+ * the daemon downloads only their validated Cumora storage keys. */
+export interface CliAttachmentRead {
+ messageId: string
+ attachments: readonly AttachmentDescriptor[]
+}
+
export interface CliResult {
ok: boolean
text: string
exitCode: number
sideEffects?: CliSideEffect[]
+ attachmentReads?: CliAttachmentRead[]
}
export interface CliSideEffectsParseResult {
diff --git a/server/src/agents/cli.ts b/server/src/agents/cli.ts
index aecfba8..68a90e9 100644
--- a/server/src/agents/cli.ts
+++ b/server/src/agents/cli.ts
@@ -11,9 +11,10 @@
import { pool } from '../db/pool.js'
import type { PoolClient } from 'pg'
-import { storage, freshenAttachmentUrl, type StoredAttachment } from '../storage.js'
+import { storage, freshenMessageAttachments, type StoredAttachment } from '../storage.js'
+import { normalizeAttachments } from '../../../shared/attachments.js'
import { env } from '../env.js'
-import type { CliResult, CliSideEffect } from './cli-result.js'
+import type { CliAttachmentRead, CliResult, CliSideEffect } from './cli-result.js'
import { fetchImageBytes } from './image-fetcher.js'
import { stripLoneSurrogates } from './text-safety.js'
import { dispatchMessagePush } from '../push.js'
@@ -26,6 +27,7 @@ import {
import { memoryMetaForWrite, resolveMemoryWriteSource } from './memory-write.js'
import { wakeKanbanAgents } from './kanban-wake.js'
import { isBoardDueOn } from './board-due-date.js'
+import { grantAttachment } from '../attachments/grants.js'
import {
enqueueBroadcast,
nudgeRealtimeOutbox,
@@ -44,11 +46,15 @@ import {
// here means CLI output (read by agents as tool results) can never carry a split
// emoji into a model transcript — the single chokepoint that covers all the
// body.slice(0, N) truncations below. See text-safety.ts.
-function ok(text: string, sideEffects?: CliSideEffect[]): CliResult {
+function ok(text: string, sideEffects?: CliSideEffect[], attachmentReads?: CliAttachmentRead[]): CliResult {
text = stripLoneSurrogates(text)
- return sideEffects && sideEffects.length > 0
- ? { ok: true, text, exitCode: 0, sideEffects }
- : { ok: true, text, exitCode: 0 }
+ return {
+ ok: true,
+ text,
+ exitCode: 0,
+ ...(sideEffects && sideEffects.length > 0 ? { sideEffects } : {}),
+ ...(attachmentReads && attachmentReads.length > 0 ? { attachmentReads } : {}),
+ }
}
function err(text: string, code = 1): CliResult {
return { ok: false, text: stripLoneSurrogates(text), exitCode: code }
@@ -235,20 +241,31 @@ async function releaseTenantWork(
* pattern in api/router.ts so a storage hiccup on one row never
* fails the whole list — falls back to the stored (possibly stale)
* URL with a warning. */
-async function freshenRowAttachment(row: { id: string; attachment: StoredAttachment | null }): Promise<void> {
- if (!row.attachment) return
+async function freshenRowAttachment(row: { id: string; attachment?: StoredAttachment | null; attachments?: readonly StoredAttachment[] | null }): Promise<void> {
+ const stored = row.attachments?.length ? row.attachments : row.attachment
+ if (!stored) return
try {
- row.attachment = await freshenAttachmentUrl(row.attachment)
+ Object.assign(row, await freshenMessageAttachments(stored))
} catch (e) {
- console.warn(`[cli] freshenAttachmentUrl failed for message ${row.id}; falling back to stored URL`, e)
+ console.warn(`[cli] freshenMessageAttachments failed for message ${row.id}; falling back to stored URL`, e)
}
}
/** One-line, agent-readable summary of an attachment. */
-function renderAttachment(att: StoredAttachment | null | undefined): string | null {
- if (!att) return null
- const size = typeof att.size === 'number' ? ` ${att.size}B` : ''
- return ` ↳ [${att.kind}] ${att.name}${size} → ${att.url}`
+function renderAttachments(value: unknown): string[] {
+ return normalizeAttachments(value).map((att) => {
+ const size = typeof att.size === 'number' ? ` ${att.size}B` : ''
+ return ` ↳ [${att.kind}] ${att.name}${size} → ${att.url ?? '(no download URL)'}`
+ })
+}
+
+function attachmentReadsFor(
+ rows: ReadonlyArray<{ id: string; attachment?: StoredAttachment | null; attachments?: readonly StoredAttachment[] | null }>,
+): CliAttachmentRead[] {
+ return rows.flatMap((row) => {
+ const attachments = normalizeAttachments(row.attachments ?? row.attachment)
+ return attachments.length > 0 ? [{ messageId: row.id, attachments }] : []
+ })
}
/* ============== commands ============== */
@@ -712,7 +729,7 @@ async function cmdMessages(parsed: ParsedArgs): Promise<CliResult> {
const limitParam = `$${params.length}`
const { rows } = await pool.query<{
id: string; author_id: string; kind: string; body: string; sequence: number;
- created_at: string; attachment: StoredAttachment | null;
+ created_at: string; attachment: StoredAttachment | null; attachments: StoredAttachment[] | null;
poll: InboxPollPayload | null;
quoted_message_id: string | null;
quoted: { id: string; authorId: string; authorName: string; body: string } | null;
@@ -734,7 +751,10 @@ async function cmdMessages(parsed: ParsedArgs): Promise<CliResult> {
)
)
SELECT
- m.id, m.author_id, m.kind, m.body, m.sequence, m.created_at, m.attachment, m.poll,
+ m.id, m.author_id, m.kind, m.body, m.sequence, m.created_at,
+ COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
+ ELSE jsonb_build_array(m.attachment) END) AS attachments,
+ COALESCE(m.attachments->0, m.attachment) AS attachment, m.poll,
m.quoted_message_id,
(
SELECT jsonb_build_object(
@@ -756,6 +776,7 @@ async function cmdMessages(parsed: ParsedArgs): Promise<CliResult> {
)
for (const row of rows) await freshenRowAttachment(row)
const inOrder = rows.reverse()
+ const attachmentReads = attachmentReadsFor(inOrder)
// Advance the Redis "seen" boundary — `cumora messages` just showed
// the agent these rows, so the highest seq here counts as "what I've
// seen" for the freshness preflight on its next `cumora reply`. Without
@@ -764,7 +785,7 @@ async function cmdMessages(parsed: ParsedArgs): Promise<CliResult> {
if (inOrder.length > 0) {
await recordSeen(me, id, inOrder[inOrder.length - 1].sequence)
}
- if (parsed.flags.json) return ok(JSON.stringify(inOrder, null, 2))
+ if (parsed.flags.json) return ok(JSON.stringify(inOrder, null, 2), undefined, attachmentReads)
if (inOrder.length === 0) {
return ok(threadRootId
? `(no replies in thread ${threadRootId})`
@@ -789,10 +810,9 @@ async function cmdMessages(parsed: ParsedArgs): Promise<CliResult> {
if (m.kind === 'poll' && m.poll) {
for (const line of renderPollBlock(m.id, m.poll)) lines.push(line)
}
- const att = renderAttachment(m.attachment)
- if (att) lines.push(att)
+ lines.push(...renderAttachments(m.attachments ?? m.attachment))
}
- return ok(lines.join('\n'))
+ return ok(lines.join('\n'), undefined, attachmentReads)
}
/** `cumora thread <convo_id> <root_msg_id> [--tail N]`
@@ -881,9 +901,12 @@ async function cmdSearch(parsed: ParsedArgs): Promise<CliResult> {
const limitParam = `$${params.length}`
const { rows } = await pool.query<{
id: string; conversation_id: string; author_id: string; body: string;
- created_at: string; attachment: StoredAttachment | null
+ created_at: string; attachment: StoredAttachment | null; attachments: StoredAttachment[] | null
}>(
- `SELECT m.id, m.conversation_id, m.author_id, m.body, m.created_at, m.attachment
+ `SELECT m.id, m.conversation_id, m.author_id, m.body, m.created_at,
+ COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
+ ELSE jsonb_build_array(m.attachment) END) AS attachments,
+ COALESCE(m.attachments->0, m.attachment) AS attachment
FROM messages m
JOIN conversations c ON c.id = m.conversation_id
JOIN participants requester
@@ -902,7 +925,8 @@ async function cmdSearch(parsed: ParsedArgs): Promise<CliResult> {
params,
)
for (const row of rows) await freshenRowAttachment(row)
- if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2))
+ const attachmentReads = attachmentReadsFor(rows)
+ if (parsed.flags.json) return ok(JSON.stringify(rows, null, 2), undefined, attachmentReads)
if (rows.length === 0) return ok(`(no matches for "${query}"${inConvo ? ` in ${inConvo}` : ''})`)
const lines = [`${rows.length} match(es) for "${query}":`, '']
for (const m of rows) {
@@ -910,10 +934,9 @@ async function cmdSearch(parsed: ParsedArgs): Promise<CliResult> {
const idx = m.body.toLowerCase().indexOf(query.toLowerCase())
const slice = m.body.slice(Math.max(0, idx - 20), idx + 100).replace(/\n/g, ' \\n ')
lines.push(` · [${t}] ${m.conversation_id} ${m.author_id}: …${slice}…`)
- const att = renderAttachment(m.attachment)
- if (att) lines.push(att)
+ lines.push(...renderAttachments(m.attachments ?? m.attachment))
}
- return ok(lines.join('\n'))
+ return ok(lines.join('\n'), undefined, attachmentReads)
}
async function cmdToolsLog(parsed: ParsedArgs): Promise<CliResult> {
@@ -994,6 +1017,7 @@ interface InboxItem {
sequence: number
created_at: string
attachment: StoredAttachment | null
+ attachments: StoredAttachment[] | null
poll: InboxPollPayload | null
quoted_message_id: string | null
quoted: InboxQuotedSummary | null
@@ -1048,7 +1072,9 @@ async function loadInbox(agentId: string): Promise<InboxItem[]> {
m.kind,
m.sequence,
m.created_at,
- m.attachment,
+ COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
+ ELSE jsonb_build_array(m.attachment) END) AS attachments,
+ COALESCE(m.attachments->0, m.attachment) AS attachment,
m.poll,
m.quoted_message_id,
(
@@ -1115,7 +1141,8 @@ async function cmdInbox(parsed: ParsedArgs): Promise<CliResult> {
const filterConvo = parsed.positional[0] ?? null
const items = await loadInbox(me)
const filtered = filterConvo ? items.filter((m) => m.conversation_id === filterConvo) : items
- if (parsed.flags.json) return ok(JSON.stringify(filtered, null, 2))
+ const attachmentReads = attachmentReadsFor(filtered)
+ if (parsed.flags.json) return ok(JSON.stringify(filtered, null, 2), undefined, attachmentReads)
if (filtered.length === 0) return ok(`(inbox empty for ${me})`)
// Group by conversation
@@ -1147,13 +1174,12 @@ async function cmdInbox(parsed: ParsedArgs): Promise<CliResult> {
if (m.kind === 'poll' && m.poll) {
for (const line of renderPollBlock(m.id, m.poll)) lines.push(line)
}
- const att = renderAttachment(m.attachment)
- if (att) lines.push(att)
+ lines.push(...renderAttachments(m.attachments ?? m.attachment))
}
lines.push('')
}
lines.push(`when you're done deciding what to do (reply / react / dm / nothing), run \`cumora ack <convo_id>\` to clear that conversation from your inbox so the next wake-up doesn't see it again. \`cumora ack --all\` clears everything in your inbox.`)
- return ok(lines.join('\n'))
+ return ok(lines.join('\n'), undefined, attachmentReads)
}
/** `cumora glance <convo>` — read the room before committing a reply.
@@ -1185,10 +1211,15 @@ async function cmdGlance(parsed: ParsedArgs): Promise<CliResult> {
body: string
created_at: string
sequence: number
+ attachment: StoredAttachment | null
+ attachments: StoredAttachment[] | null
}
const { rows } = await pool.query<RecentRow>(
`SELECT m.id, m.author_id, COALESCE(p.name, m.author_id) AS author_name,
- m.kind, m.body, m.created_at, m.sequence
+ m.kind, m.body, m.created_at, m.sequence,
+ COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
+ ELSE jsonb_build_array(m.attachment) END) AS attachments,
+ COALESCE(m.attachments->0, m.attachment) AS attachment
FROM messages m
JOIN conversations c ON c.id = m.conversation_id
JOIN participants requester
@@ -1208,7 +1239,9 @@ async function cmdGlance(parsed: ParsedArgs): Promise<CliResult> {
LIMIT 12`,
[convoId, me, companyId],
)
+ for (const row of rows) await freshenRowAttachment(row)
const recent = rows.reverse()
+ const attachmentReads = attachmentReadsFor(recent)
// Advance the Redis "seen" boundary — glance just showed the agent
// these messages, so they count as "seen" for the freshness preflight
@@ -1229,7 +1262,7 @@ async function cmdGlance(parsed: ParsedArgs): Promise<CliResult> {
// and the server's freshness gate (cmdReply preflight) serializes collisions.
// glance now returns ONLY the stream, matching that model.
if (parsed.flags.json) {
- return ok(JSON.stringify({ conversation_id: convoId, recent }, null, 2))
+ return ok(JSON.stringify({ conversation_id: convoId, recent }, null, 2), undefined, attachmentReads)
}
const lines: string[] = []
@@ -1247,9 +1280,10 @@ async function cmdGlance(parsed: ParsedArgs): Promise<CliResult> {
? '[system]'
: m.body.slice(0, 200).replace(/\n/g, ' \\n ')
lines.push(` [${m.id}] ${tag} ${t} ${m.author_name}: ${body}`)
+ lines.push(...renderAttachments(m.attachments ?? m.attachment))
}
}
- return ok(lines.join('\n'))
+ return ok(lines.join('\n'), undefined, attachmentReads)
}
async function cmdAck(parsed: ParsedArgs): Promise<CliResult> {
@@ -2250,7 +2284,7 @@ async function cmdReply(parsed: ParsedArgs): Promise<CliResult> {
// as the body and uses --attach-text to mark it as an attachment.
const content = String(parsed.flags['attach-text-content'] ?? body)
if (!filename || !content) return err('--attach-text requires a filename and content')
- attachment = await saveTextAttachment(filename, content)
+ attachment = await saveTextAttachment(filename, content, companyId)
} else if (parsed.flags['attach-bytes']) {
const filename = String(parsed.flags['attach-bytes']).trim().slice(0, 200)
const b64 = String(parsed.flags['bytes-b64'] ?? '').trim()
@@ -2259,7 +2293,7 @@ async function cmdReply(parsed: ParsedArgs): Promise<CliResult> {
: undefined
if (!filename || !b64) return err('--attach-bytes requires a filename and --bytes-b64 "<base64>"')
try {
- attachment = await saveBytesAttachment(filename, b64, mime)
+ attachment = await saveBytesAttachment(filename, b64, mime, companyId)
} catch (e) {
return err(`attach-bytes failed: ${e instanceof Error ? e.message : String(e)}`)
}
@@ -2373,9 +2407,10 @@ async function cmdReply(parsed: ParsedArgs): Promise<CliResult> {
}
}
await txClient.query(
- `INSERT INTO messages (id, conversation_id, author_id, kind, body, sequence, attachment, quoted_message_id, company_id)
- VALUES ($1,$2,$3,'text',$4,$5,$6::jsonb,$7,$8)`,
- [messageId, convoId, me, finalBody, sequence, attachment ? JSON.stringify(attachment) : null, resolvedQuotedId, companyId],
+ `INSERT INTO messages (id, conversation_id, author_id, kind, body, sequence, attachment, attachments, quoted_message_id, company_id)
+ VALUES ($1,$2,$3,'text',$4,$5,$6::jsonb,$7::jsonb,$8,$9)`,
+ [messageId, convoId, me, finalBody, sequence, attachment ? JSON.stringify(attachment) : null,
+ attachment ? JSON.stringify([attachment]) : '[]', resolvedQuotedId, companyId],
)
await txClient.query(`UPDATE conversations SET updated_at = NOW() WHERE id = $1`, [convoId])
await txClient.query(
@@ -2397,6 +2432,7 @@ async function cmdReply(parsed: ParsedArgs): Promise<CliResult> {
sequence,
at: new Date().toISOString(),
attachment: attachment ?? undefined,
+ attachments: attachment ? [attachment] : [],
quotedMessageId: resolvedQuotedId ?? undefined,
quoted: quotedSummary
? {
@@ -2535,6 +2571,7 @@ async function generateAndUploadImage(opts: {
const id = randomUUID().replace(/-/g, '')
const key = `attachments/${id}.png`
const url = await storage.put(key, buf, 'image/png')
+ if (opts.tenant) await grantAttachment(pool, opts.tenant, key)
// Slug the prompt into a friendly filename for the bubble caption.
const slug = opts.prompt
.toLowerCase()
@@ -2624,6 +2661,7 @@ async function saveBytesAttachment(
filename: string,
base64: string,
mimeHint?: string,
+ tenant?: string,
): Promise<{ url: string; name: string; kind: 'img' | 'file'; mime: string; size: number; key: string }> {
// Generous 32 MB ceiling — same as the user-upload edge. The base64
// wire form is ~33% larger; we decode first then re-check.
@@ -2647,6 +2685,7 @@ async function saveBytesAttachment(
const id = randomUUID().replace(/-/g, '')
const key = `attachments/${id}.${ext}`
const url = await storage.put(key, buf, mime)
+ if (tenant) await grantAttachment(pool, tenant, key)
return { url, key, name: filename, kind, mime, size: buf.length }
}
@@ -3852,6 +3891,7 @@ async function setAgentAvatarFromUrl(args: {
async function saveTextAttachment(
filename: string,
content: string,
+ tenant?: string,
): Promise<{ url: string; name: string; kind: 'file'; mime: string; size: number; key: string }> {
// Sniff a reasonable mime from the extension so the renderer + agent
// both know how to handle it (text/* gets inlined into context on read).
@@ -3873,6 +3913,7 @@ async function saveTextAttachment(
const id = randomUUID().replace(/-/g, '')
const key = `attachments/${id}.${ext}`
const url = await storage.put(key, buf, mime)
+ if (tenant) await grantAttachment(pool, tenant, key)
return { url, key, name: filename, kind: 'file', mime, size: buf.length }
}
diff --git a/server/src/agents/computer/attachment-cache.ts b/server/src/agents/computer/attachment-cache.ts
new file mode 100644
index 0000000..4c9cadc
--- /dev/null
+++ b/server/src/agents/computer/attachment-cache.ts
@@ -0,0 +1,279 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { chmod, lstat, mkdir, readdir, rename, rm, stat, utimes, writeFile } from 'node:fs/promises'
+import { extname, join } from 'node:path'
+import {
+ ATTACHMENT_MAX_FILE_BYTES,
+ ATTACHMENT_TEXT_EXCERPT_BYTES,
+ normalizeAttachments,
+ type AttachmentDescriptor,
+} from '../../../../shared/attachments.js'
+import { normalizeStorageKey } from '../../storage-keys.js'
+import type { VisionCapability } from './model-capabilities.js'
+
+const DOWNLOAD_TIMEOUT_MS = 20_000
+export const ATTACHMENT_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000
+export const ATTACHMENT_CACHE_MAX_BYTES = 1024 * 1024 * 1024
+
+export interface AttachmentCacheOptions {
+ readonly maxAgeMs?: number
+ readonly maxBytes?: number
+ readonly now?: () => number
+}
+
+export interface AttachmentCacheCleanupResult {
+ readonly removedFiles: number
+ readonly removedBytes: number
+ readonly remainingBytes: number
+}
+
+export interface CachedAttachment {
+ readonly attachment: AttachmentDescriptor
+ readonly path: string
+ readonly text?: string
+ readonly textTruncated?: boolean
+}
+
+export interface AttachmentCacheResult {
+ readonly files: readonly CachedAttachment[]
+ readonly failures: ReadonlyArray<{ name: string; reason: string; key?: string }>
+}
+
+export function isImageAttachment(attachment: AttachmentDescriptor): boolean {
+ return attachment.kind === 'img' || attachment.mime?.startsWith('image/') === true
+}
+
+function safeName(name: string): string {
+ const base = name.normalize('NFKC').replace(/[\\/\u0000-\u001f\u007f]/g, '_').trim()
+ const cleaned = base.replace(/^\.+/, '').replace(/[<>:"|?*]/g, '_').slice(0, 160)
+ return cleaned || 'attachment'
+}
+
+function textual(mime: string | undefined): boolean {
+ const normalized = mime?.toLowerCase() ?? ''
+ return normalized.startsWith('text/') || [
+ 'application/json', 'application/x-yaml', 'application/x-toml',
+ 'application/xml', 'application/javascript', 'application/sql',
+ ].includes(normalized)
+}
+
+async function ensureCacheDirectory(path: string): Promise<void> {
+ try {
+ await mkdir(path, { recursive: true, mode: 0o700 })
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code
+ if (code !== 'EEXIST') throw error
+ }
+ const info = await lstat(path)
+ if (!info.isDirectory() || info.isSymbolicLink()) {
+ throw new Error('attachment cache path is not a private directory')
+ }
+ await chmod(path, 0o700)
+}
+
+/** Download every attachment through the runtime JWT endpoint into this
+ * agent's home. The model never receives the bearer token or chooses a URL. */
+export class AgentAttachmentCache {
+ private readonly activePaths = new Set<string>()
+ private turnDepth = 0
+ private readonly maxAgeMs: number
+ private readonly maxBytes: number
+ private readonly now: () => number
+
+ constructor(
+ private readonly homeRoot: string,
+ private readonly serverUrl: string,
+ private readonly getToken: () => Promise<string>,
+ private readonly fetchImpl: typeof fetch = fetch,
+ options: AttachmentCacheOptions = {},
+ ) {
+ this.maxAgeMs = options.maxAgeMs ?? ATTACHMENT_CACHE_MAX_AGE_MS
+ this.maxBytes = options.maxBytes ?? ATTACHMENT_CACHE_MAX_BYTES
+ this.now = options.now ?? Date.now
+ if (!Number.isFinite(this.maxAgeMs) || this.maxAgeMs < 0) {
+ throw new Error('attachment cache maxAgeMs must be a non-negative finite number')
+ }
+ if (!Number.isFinite(this.maxBytes) || this.maxBytes < 0) {
+ throw new Error('attachment cache maxBytes must be a non-negative finite number')
+ }
+ }
+
+ /** Mark paths produced during a model turn as live. Cleanup never removes
+ * them until the corresponding turn has finished. */
+ beginTurn(): void {
+ this.turnDepth += 1
+ }
+
+ /** Release the current-turn protection and run the bounded local cleanup. */
+ async endTurn(): Promise<AttachmentCacheCleanupResult> {
+ this.turnDepth = Math.max(0, this.turnDepth - 1)
+ if (this.turnDepth > 0) {
+ return this.cleanup()
+ }
+ this.activePaths.clear()
+ const result = await this.cleanup()
+ return result
+ }
+
+ /** Reap expired and least-recently-used files under this Agent's home.
+ * Symlinks and directories are never followed. Active turn paths are
+ * protected even when the cache is over its size limit. */
+ async cleanup(): Promise<AttachmentCacheCleanupResult> {
+ const root = join(this.homeRoot, 'attachments')
+ const entries: Array<{ path: string; size: number; atimeMs: number }> = []
+ try {
+ const messages = await readdir(root, { withFileTypes: true })
+ for (const message of messages) {
+ if (!message.isDirectory() || message.isSymbolicLink()) continue
+ const directory = join(root, message.name)
+ const files = await readdir(directory, { withFileTypes: true }).catch((error: unknown) => {
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+ throw error
+ })
+ for (const file of files) {
+ if (!file.isFile() || file.isSymbolicLink()) continue
+ const path = join(directory, file.name)
+ try {
+ const info = await stat(path)
+ if (!info.isFile()) continue
+ entries.push({ path, size: info.size, atimeMs: Math.max(info.atimeMs, info.mtimeMs) })
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+ }
+ }
+ }
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code
+ if (code !== 'ENOENT' && code !== 'ENOTDIR') throw error
+ return { removedFiles: 0, removedBytes: 0, remainingBytes: 0 }
+ }
+
+ const now = this.now()
+ const expired = entries.filter((entry) =>
+ !this.activePaths.has(entry.path) && now - entry.atimeMs >= this.maxAgeMs,
+ )
+ const candidates = entries
+ .filter((entry) => !this.activePaths.has(entry.path) && !expired.includes(entry))
+ .sort((a, b) => a.atimeMs - b.atimeMs)
+ const expiredPaths = new Set(expired.map((entry) => entry.path))
+ let remainingBytes = entries.reduce((sum, entry) => sum + entry.size, 0)
+ const remove = [...expired, ...candidates]
+ let removedFiles = 0
+ let removedBytes = 0
+ for (const entry of remove) {
+ if (!expiredPaths.has(entry.path) && remainingBytes <= this.maxBytes) break
+ try {
+ await rm(entry.path, { force: true })
+ removedFiles += 1
+ removedBytes += entry.size
+ remainingBytes -= entry.size
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+ }
+ }
+ return { removedFiles, removedBytes, remainingBytes: Math.max(0, remainingBytes) }
+ }
+
+ /** Sweep after the runner has stopped. Persistent engine sessions may still
+ * refer to paths from earlier turns, so keep unexpired files unless the
+ * owning Agent is being removed. */
+ async dispose(options: { purge?: boolean } = {}): Promise<void> {
+ this.activePaths.clear()
+ this.turnDepth = 0
+ if (options.purge) {
+ await rm(join(this.homeRoot, 'attachments'), { recursive: true, force: true })
+ return
+ }
+ await this.cleanup()
+ }
+
+ async materialize(messageId: string, value: unknown): Promise<AttachmentCacheResult> {
+ await this.cleanup()
+ const safeMessage = messageId.replace(/[^a-z0-9._-]/gi, '_').slice(0, 160) || createHash('sha256')
+ .update(messageId).digest('hex').slice(0, 16)
+ const directory = join(this.homeRoot, 'attachments', safeMessage)
+ await ensureCacheDirectory(join(this.homeRoot, 'attachments'))
+ await ensureCacheDirectory(directory)
+ const token = await this.getToken()
+ const files: CachedAttachment[] = []
+ const failures: Array<{ name: string; reason: string; key?: string }> = []
+
+ for (const [index, attachment] of normalizeAttachments(value).entries()) {
+ const key = normalizeStorageKey(attachment.key ?? '')
+ if (!key?.startsWith('attachments/')) {
+ failures.push({ name: attachment.name, reason: 'missing trusted Cumora attachment key' })
+ continue
+ }
+ try {
+ const target = new URL(
+ `${this.serverUrl.replace(/\/+$/, '')}/runtime/attachment?key=${encodeURIComponent(key)}&messageId=${encodeURIComponent(messageId)}`,
+ )
+ const response = await this.fetchImpl(
+ target,
+ {
+ headers: { Authorization: `Bearer ${token}` },
+ redirect: 'follow',
+ signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+ },
+ )
+ if (!response.ok) throw new Error(`HTTP ${response.status}`)
+ const declared = Number(response.headers.get('content-length') ?? 0)
+ if (declared > ATTACHMENT_MAX_FILE_BYTES) throw new Error('attachment exceeds 25 MiB')
+ const bytes = Buffer.from(await response.arrayBuffer())
+ if (bytes.length === 0) throw new Error('attachment is empty')
+ if (bytes.length > ATTACHMENT_MAX_FILE_BYTES) throw new Error('attachment exceeds 25 MiB')
+ const extension = extname(safeName(attachment.name)).replace(/[^.a-z0-9]/gi, '').slice(0, 16)
+ const file = join(directory, `${index + 1}-${createHash('sha256').update(key).digest('hex').slice(0, 16)}${extension}`)
+ const staged = `${file}.${process.pid}.${randomUUID()}.tmp`
+ try {
+ await writeFile(staged, bytes, { mode: 0o600, flag: 'wx' })
+ await chmod(staged, 0o600).catch(() => {})
+ await rename(staged, file)
+ } finally {
+ await rm(staged, { force: true }).catch(() => {})
+ }
+ if (this.turnDepth > 0) this.activePaths.add(file)
+ // Keep the local file's access time fresh for LRU cleanup. This is
+ // best effort because some filesystems disable atime updates.
+ await utimes(file, new Date(), new Date()).catch(() => {})
+ files.push({
+ attachment,
+ path: file,
+ ...(textual(attachment.mime) ? {
+ text: bytes.subarray(0, ATTACHMENT_TEXT_EXCERPT_BYTES).toString('utf8'),
+ textTruncated: bytes.length > ATTACHMENT_TEXT_EXCERPT_BYTES,
+ } : {}),
+ })
+ } catch (error) {
+ failures.push({ name: attachment.name, key, reason: error instanceof Error ? error.message : 'download failed' })
+ }
+ }
+ return { files, failures }
+ }
+}
+
+export function attachmentImageGuidance(vision: VisionCapability): string {
+ if (vision === 'supported') {
+ return 'This image is in your Agent home. Use native image input or image viewing on this path before relying on visual details.'
+ }
+ if (vision === 'unsupported') {
+ return 'The active model does not support image input. Do not claim to have seen this image.'
+ }
+ return 'Visual support is unknown. If you have a native image viewer, use the local path to inspect this image. Do not claim to have seen it unless image viewing succeeds.'
+}
+
+export function renderCachedAttachments(result: AttachmentCacheResult, vision: VisionCapability): string {
+ const lines: string[] = []
+ for (const file of result.files) {
+ lines.push(`Attachment "${file.attachment.name}": ${file.path}`)
+ if (isImageAttachment(file.attachment)) {
+ lines.push(attachmentImageGuidance(vision))
+ }
+ if (file.text !== undefined) {
+ lines.push(`File excerpt${file.textTruncated ? ' (first 50 KiB)' : ''}:`, '```', file.text, '```')
+ }
+ }
+ for (const failure of result.failures) {
+ lines.push(`Attachment "${failure.name}" could not be downloaded: ${failure.reason}`)
+ }
+ return lines.join('\n')
+}
diff --git a/server/src/agents/computer/daemon.ts b/server/src/agents/computer/daemon.ts
index ff6cdeb..67b8a8a 100644
--- a/server/src/agents/computer/daemon.ts
+++ b/server/src/agents/computer/daemon.ts
@@ -51,12 +51,14 @@ import {
import { SKYPE_EMOTICONS_GUIDE } from '../skype-emoticons.js'
import { finalizeTriage, isRateLimited, parseTriage } from '../triage-core.js'
import { type ActionSurface, actionSurfaceFor, actionSurfaceText, calendarExampleText, postingMechanicsText } from './prompt-surface.js'
-import { allowUnsandboxedByoa, classifyEngineFailure, detectEnginesWithStatus, ENGINE_IDS, engineFailureOf, type DetectedEngineSnapshot, type EngineHopReport, type EngineId, type EngineRunResult, type EngineSession, type EngineUsage, enrichDetectedEngines, evaluateRunnableEngines, getAdapter, loginCodexRuntime, runEngineDoctor, type RunnableEngineEvaluation, snapshotDetectedEngines } from './engine.js'
+import { allowUnsandboxedByoa, classifyEngineFailure, detectEnginesWithStatus, ENGINE_IDS, engineFailureOf, engineVisionCapability, type DetectedEngineSnapshot, type EngineHopReport, type EngineId, type EngineRunResult, type EngineSession, type EngineUsage, enrichDetectedEngines, evaluateRunnableEngines, getAdapter, loginCodexRuntime, runEngineDoctor, type RunnableEngineEvaluation, snapshotDetectedEngines } from './engine.js'
import { EngineSessionStore, sessionIdPreview } from './session-store.js'
import { CODEX_LOGIN_COMMAND, CODEX_MIGRATE_COMMAND, CODEX_SESSION_SCOPE, codexRuntimeHome } from './codex-runtime.js'
import { cachedCodexProvider } from './codex-provider.js'
import { migrateCodexSession, migrateCodexSessions } from './codex-session-migration.js'
import { runWithSessionRecovery } from './session-recovery.js'
+import { normalizeAttachments, type AttachmentDescriptor } from '../../../../shared/attachments.js'
+import { AgentAttachmentCache, attachmentImageGuidance, isImageAttachment, renderCachedAttachments, type AttachmentCacheResult } from './attachment-cache.js'
export { conversationHeader }
@@ -464,19 +466,14 @@ interface AgentInfo {
model: string | null
fastModel: string | null
nativeFastMode?: boolean
+ modelCatalog?: {
+ models: Array<{ id: string; label: string; vision?: 'supported' | 'unsupported' | 'unknown' }>
+ defaultModel: string | null
+ }
}
-/** One line's worth of "there is a file on this message".
- *
- * The attachment already travelled: /inbox selects `m.attachment` and the
- * daemon received it. It was simply never rendered, so a BYOA agent saw the
- * text of a message and no sign that a file came with it — and said so, truthfully,
- * when a user asked why it could not see their zip. The cloud path (turn.ts)
- * has always surfaced attachments; only this one dropped them.
- *
- * Name, type and size go inline so the agent can reason about the file, and the
- * URL follows so it can actually fetch it. Bounded, because this shares the
- * digest's line budget with the message bodies. */
+/** Render one attachment descriptor in the inbox digest. The daemon separately
+ * downloads authorized bytes into the Agent home. */
export function attachmentNote(
att: { name?: string; kind?: string; mime?: string; size?: number; url?: string } | null | undefined,
): string {
@@ -492,6 +489,85 @@ export function attachmentNote(
return ` [attachment: ${name}${type ? ` · ${type}` : ''}${size}${url}]`
}
+/** Render every descriptor in canonical order. The singular helper remains for
+ * legacy callers and tests; the digest always goes through this list boundary. */
+export function attachmentNotes(value: unknown): string {
+ return normalizeAttachments(value).map((attachment) => attachmentNote({
+ name: attachment.name,
+ kind: attachment.kind,
+ mime: attachment.mime,
+ size: attachment.size,
+ })).join('')
+}
+
+interface RuntimeCliAttachmentRead {
+ messageId: string
+ attachments: AttachmentDescriptor[]
+}
+
+function runtimeCliAttachmentReads(value: unknown): RuntimeCliAttachmentRead[] {
+ if (!Array.isArray(value)) return []
+ const reads: RuntimeCliAttachmentRead[] = []
+ for (const candidate of value.slice(0, 200)) {
+ if (!candidate || typeof candidate !== 'object') continue
+ const record = candidate as Record<string, unknown>
+ if (typeof record.messageId !== 'string' || !record.messageId) continue
+ const attachments = normalizeAttachments(record.attachments)
+ if (attachments.length > 0) reads.push({ messageId: record.messageId, attachments: [...attachments] })
+ }
+ return reads
+}
+
+/** Add the local path to each attachment object inside the CLI's JSON result.
+ * JSON output stays valid instead of receiving a trailing prose block. */
+export function enrichCliJsonWithAttachmentPaths(
+ text: string,
+ cachedByMessage: ReadonlyMap<string, AttachmentCacheResult>,
+ vision: 'supported' | 'unsupported' | 'unknown',
+): string | null {
+ let value: unknown
+ try { value = JSON.parse(text) } catch { return null }
+ const visit = (node: unknown): void => {
+ if (!node || typeof node !== 'object') return
+ if (Array.isArray(node)) {
+ for (const item of node) visit(item)
+ return
+ }
+ const record = node as Record<string, unknown>
+ const messageId = typeof record.id === 'string' ? record.id : null
+ const cached = messageId ? cachedByMessage.get(messageId) : undefined
+ if (cached) {
+ for (const field of ['attachments', 'attachment'] as const) {
+ const raw = record[field]
+ const list = Array.isArray(raw) ? raw : raw && typeof raw === 'object' ? [raw] : []
+ for (const attachment of list) {
+ if (!attachment || typeof attachment !== 'object') continue
+ const descriptor = attachment as Record<string, unknown>
+ const key = typeof descriptor.key === 'string' ? descriptor.key : null
+ const file = cached.files.find((candidate) => candidate.attachment.key === key)
+ if (file) {
+ descriptor.localPath = file.path
+ if (file.attachment.kind === 'img' || file.attachment.mime?.startsWith('image/') === true) {
+ descriptor.localImageGuidance = attachmentImageGuidance(vision)
+ }
+ if (file.text !== undefined) {
+ descriptor.localText = file.text
+ descriptor.localTextTruncated = file.textTruncated === true
+ }
+ } else {
+ const failure = cached.failures.find((candidate) => candidate.key === key)
+ ?? cached.failures.find((candidate) => !candidate.key && candidate.name === descriptor.name)
+ if (failure) descriptor.localError = failure.reason
+ }
+ }
+ }
+ }
+ for (const child of Object.values(record)) visit(child)
+ }
+ visit(value)
+ return JSON.stringify(value, null, 2)
+}
+
interface RuntimeInboxResponse {
rows?: Array<{
id?: string
@@ -505,9 +581,10 @@ interface RuntimeInboxResponse {
author_kind?: string
body?: string
kind?: string
- /** Already delivered by /inbox (loadInbox selects m.attachment) and, until
- * now, dropped on the floor when the digest line was built. */
- attachment?: { name?: string; kind?: string; mime?: string; size?: number; url?: string } | null
+ /** Legacy first-entry projection for clients that predate multi-attachments. */
+ attachment?: AttachmentDescriptor | null
+ /** Canonically ordered message attachments. */
+ attachments?: AttachmentDescriptor[]
sequence?: number
}>
}
@@ -535,11 +612,16 @@ const DIGEST_MAX_MESSAGE_LINES = 40
* shown, exactly as before.
*
* Exported for tests — pure, no server and no engine. */
-export function renderInboxDigest(
- byConvo: Map<string, { head: string; msgs: string[] }>,
- budget = DIGEST_MAX_MESSAGE_LINES,
-): string {
- if (byConvo.size === 0) return ''
+interface InboxDigestConversation {
+ head: string
+ msgs: string[]
+ ids?: string[]
+}
+
+function inboxDigestKeepCounts(
+ byConvo: Map<string, InboxDigestConversation>,
+ budget: number,
+): Map<string, number> {
// Water-fill quietest-first: each conversation takes at most an even share of
// what is LEFT, so a small conversation keeps all of its messages and the busy
// one absorbs the slack. When the total fits, this hands every conversation
@@ -553,6 +635,31 @@ export function renderInboxDigest(
lineBudget -= n
unserved -= 1
}
+ return keep
+}
+
+/** IDs represented by the rendered digest lines. Attachment materialization
+ * uses the same water-fill decision so it downloads exactly what the engine
+ * is shown, rather than every unread row returned by /inbox. */
+export function visibleInboxMessageIds(
+ byConvo: Map<string, InboxDigestConversation>,
+ budget = DIGEST_MAX_MESSAGE_LINES,
+): Set<string> {
+ const keep = inboxDigestKeepCounts(byConvo, budget)
+ const visible = new Set<string>()
+ for (const [id, convo] of byConvo) {
+ const shown = keep.get(id) ?? 0
+ for (const messageId of (convo.ids ?? []).slice(convo.msgs.length - shown)) visible.add(messageId)
+ }
+ return visible
+}
+
+export function renderInboxDigest(
+ byConvo: Map<string, InboxDigestConversation>,
+ budget = DIGEST_MAX_MESSAGE_LINES,
+): string {
+ if (byConvo.size === 0) return ''
+ const keep = inboxDigestKeepCounts(byConvo, budget)
const lines: string[] = []
for (const [id, convo] of byConvo) {
const shown = keep.get(id) ?? 0
@@ -1868,6 +1975,9 @@ export class AgentRunner {
private lastPostedStatus: string | null = null
private lastPostedStatusAt = 0
private readonly adapter
+ /** Per-agent attachment cache. A long-lived instance lets cleanup protect
+ * paths used by the current turn and reap them when the runner stops. */
+ private readonly attachmentCache: AgentAttachmentCache
/** Privileged local broker: the engine sees only its IPC directory, while the
* daemon keeps the short-lived runtime JWT in memory. */
private cliBroker: RuntimeCliBroker | null = null
@@ -1896,6 +2006,11 @@ export class AgentRunner {
// granted only the two leaf request/response directories; Claude reaches
// them through the fixed MCP bridge, not a model-controlled shell.
this.ipcDir = join(CONFIG_DIR, '.runtime-cli-ipc', this.agent.id)
+ this.attachmentCache = new AgentAttachmentCache(
+ this.home,
+ this.cfg.serverUrl,
+ () => this.ensureToken(),
+ )
// The profile is a third dimension of session identity alongside agent and
// engine: a different endpoint/account owns a different transcript, so its
// session id must never be offered to another profile's provider.
@@ -2020,15 +2135,20 @@ export class AgentRunner {
/** Execute exactly one engine attempt. Session capture and the persistent to
* one-shot transport fallback live here so chat and agenda cannot drift. */
- private async runEngineAttempt(delta: string, resumeSessionId: string | null): Promise<EngineRunResult> {
+ private async runEngineAttempt(
+ delta: string,
+ resumeSessionId: string | null,
+ localImages: readonly string[] = [],
+ ): Promise<EngineRunResult> {
const session = this.ensureEngineSession(resumeSessionId)
const prompt = this.turnPrompt(session, delta)
+ const nativeImages = this.nativeImagePaths(localImages)
let result: EngineRunResult
if (session) {
const capture = setInterval(() => { if (session.sessionId) this.setSessionId(session.sessionId) }, 2000)
capture.unref?.()
try {
- result = await this.trackEngineRun(session.send(prompt))
+ result = await this.trackEngineRun(session.send(prompt, nativeImages))
} finally {
clearInterval(capture)
}
@@ -2050,6 +2170,8 @@ export class AgentRunner {
fastModel: this.engineFastModel(),
nativeFastMode: this.agent.nativeFastMode ?? false,
resumeSessionId,
+ vision: this.visionCapability(),
+ localImages: nativeImages,
onLog: (line) => this.logEngineLine(line),
onHopUsage: (r) => this.onEngineHop(r, 'agent-turn'),
signal: this.teardown.signal,
@@ -2064,6 +2186,8 @@ export class AgentRunner {
fastModel: this.engineFastModel(),
nativeFastMode: this.agent.nativeFastMode ?? false,
resumeSessionId,
+ vision: this.visionCapability(),
+ localImages: nativeImages,
onLog: (line) => this.logEngineLine(line),
onHopUsage: (r) => this.onEngineHop(r, 'agent-turn'),
signal: this.teardown.signal,
@@ -2076,11 +2200,14 @@ export class AgentRunner {
/** A missing resume target proves the model never began the requested turn,
* so one fresh retry is safe. Every other failure returns immediately to
* avoid duplicating tool side effects after an ambiguous crash or timeout. */
- private async runWithSessionRecovery(delta: string): Promise<EngineRunResult> {
+ private async runWithSessionRecovery(
+ delta: string,
+ localImages: readonly string[] = [],
+ ): Promise<EngineRunResult> {
const resumeSessionId = this.resumeSessionId()
return runWithSessionRecovery({
resumeSessionId,
- run: (resume) => this.runEngineAttempt(delta, resume),
+ run: (resume) => this.runEngineAttempt(delta, resume, localImages),
reset: () => this.resetEngineSession(`${this.engine} resume target ${sessionIdPreview(resumeSessionId ?? '')} does not exist`),
onFreshRetry: () => console.warn(`[computer] ${this.agent.id} retrying turn once with a fresh ${this.engine} session`),
})
@@ -2159,7 +2286,7 @@ export class AgentRunner {
if (this.wakeDebounceTimer) { clearTimeout(this.wakeDebounceTimer); this.wakeDebounceTimer = null }
}
- async stop(options: { forceEngine?: boolean } = {}): Promise<void> {
+ async stop(options: { forceEngine?: boolean; purgeAttachments?: boolean } = {}): Promise<void> {
this.beginStop()
const session = this.engineSession
this.engineSession = null
@@ -2179,6 +2306,9 @@ export class AgentRunner {
this.activeEngineRun ?? Promise.resolve(),
this.activeTriage ?? Promise.resolve(),
])
+ await this.attachmentCache.dispose({ purge: options.purgeAttachments === true }).catch((error) => {
+ console.warn(`[computer] ${this.agent.id} attachment cache cleanup failed`, error)
+ })
await this.sessionStore.flush()
}
@@ -2239,9 +2369,32 @@ export class AgentRunner {
const body = await res.text().catch(() => '')
return { exitCode: 70, error: `HTTP ${res.status} ${body.slice(0, 200)}`.trim() }
}
- const data = await res.json() as { text?: unknown; exitCode?: unknown }
+ const data = await res.json() as { text?: unknown; exitCode?: unknown; attachmentReads?: unknown }
+ let text = typeof data.text === 'string' ? data.text : ''
+ const reads = runtimeCliAttachmentReads(data.attachmentReads)
+ const cachedByMessage = new Map<string, AttachmentCacheResult>()
+ if (reads.length > 0) {
+ for (const read of reads) {
+ cachedByMessage.set(read.messageId, await this.attachmentCache.materialize(read.messageId, read.attachments))
+ }
+ const trimmed = text.trimStart()
+ const enriched = trimmed.startsWith('{') || trimmed.startsWith('[')
+ ? enrichCliJsonWithAttachmentPaths(text, cachedByMessage, this.visionCapability())
+ : null
+ if (enriched !== null) {
+ text = enriched
+ } else if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+ console.warn(`[computer] ${this.agent.id} CLI returned unparseable JSON with attachments`)
+ } else {
+ const blocks = [...cachedByMessage.entries()]
+ .map(([messageId, cached]) =>
+ `Message ${messageId}:\n${renderCachedAttachments(cached, this.visionCapability())}`)
+ .filter((block) => block.trim().length > 0)
+ if (blocks.length > 0) text += `\n\nAttachment files cached in your Agent home:\n${blocks.join('\n\n')}`
+ }
+ }
return {
- text: typeof data.text === 'string' ? data.text : '',
+ text,
exitCode: typeof data.exitCode === 'number' ? data.exitCode : 0,
}
} catch (err) {
@@ -2307,6 +2460,7 @@ export class AgentRunner {
nativeFastMode: this.agent.nativeFastMode ?? false,
resumeSessionId,
standingPrompt: this.standingPrompt(),
+ vision: this.visionCapability(),
onLog: (line) => this.logEngineLine(line),
// Trajectory hook — every assistant hop (Claude) / turn-completed (Codex)
// shows up here and gets batched to the universal ledger. Purpose is
@@ -2582,7 +2736,7 @@ export class AgentRunner {
} catch { return null }
}
- private async snapshotUnread(token: string): Promise<{ seen: Map<string, string>; digest: string; hasReal: boolean; projectIds: string[] }> {
+ private async snapshotUnread(token: string): Promise<{ seen: Map<string, string>; digest: string; hasReal: boolean; projectIds: string[]; imagePaths: string[] }> {
const inbox = await runtimeGet<RuntimeInboxResponse>(this.cfg.serverUrl, '/inbox', token)
this.lastInboxDrainAt = inbox ? Date.now() : 0
if (!inbox) throw new Error('inbox fetch failed')
@@ -2593,7 +2747,7 @@ export class AgentRunner {
// Grouped rather than one flat line list because the digest has a LINE
// BUDGET, and spending it per conversation is what stops a busy room from
// evicting — and `ackSeen` then burying — a quiet one. See renderInboxDigest.
- const byConvo = new Map<string, { head: string; msgs: string[] }>()
+ const byConvo = new Map<string, InboxDigestConversation>()
// `hasReal` = is ANY unread a genuine human/agent message (not a system
// relay/status/membership notice)? The cost gate in runTurn uses this to
// refuse to spend ANY model on a system-only (or empty) inbox.
@@ -2617,7 +2771,7 @@ export class AgentRunner {
conversation_topic: row.conversation_topic,
project_name: row.project_name,
})
- convo = { head, msgs: [] }
+ convo = { head, msgs: [], ids: [] }
byConvo.set(row.conversation_id, convo)
}
const author = row.author_name ?? 'someone'
@@ -2630,12 +2784,46 @@ export class AgentRunner {
// Keep the message id + convo id on each line (like the cloud agent's
// context) so the engine can QUOTE the exact message: `cumora reply
// <convo> '<body>' --quote <message_id>`.
- convo.msgs.push(` [${row.id}] ${row.conversation_id} ${who}: ${body}${attachmentNote(row.attachment)}`)
+ convo.msgs.push(` [${row.id}] ${row.conversation_id} ${who}: ${body}${attachmentNotes(row.attachments ?? row.attachment)}`)
+ if (row.id) convo.ids?.push(row.id)
+ }
+ const attachmentBlocks: string[] = []
+ const imagePaths: string[] = []
+ const visibleMessageIds = visibleInboxMessageIds(byConvo)
+ for (const row of inbox.rows ?? []) {
+ if (!row.id || !visibleMessageIds.has(row.id)) continue
+ const descriptors = normalizeAttachments(row.attachments ?? row.attachment)
+ if (descriptors.length === 0) continue
+ const cached = await this.attachmentCache.materialize(row.id, descriptors)
+ for (const file of cached.files) {
+ if (isImageAttachment(file.attachment)) imagePaths.push(file.path)
+ }
+ const block = renderCachedAttachments(cached, this.visionCapability())
+ if (block) attachmentBlocks.push(`Message ${row.id}:\n${block}`)
}
const projectIds = uniqueProjectIds(
(inbox?.rows ?? []).map((r) => (typeof r.project_id === 'string' ? r.project_id : null)),
)
- return { seen, digest: renderInboxDigest(byConvo), hasReal, projectIds }
+ const digest = renderInboxDigest(byConvo)
+ return {
+ seen,
+ digest: `${digest}${attachmentBlocks.length ? `\n\nAttachment files cached in your Agent home:\n${attachmentBlocks.join('\n\n')}` : ''}`,
+ hasReal,
+ projectIds,
+ imagePaths: [...new Set(imagePaths)],
+ }
+ }
+
+ private visionCapability(): 'supported' | 'unsupported' | 'unknown' {
+ return engineVisionCapability(this.agent.modelCatalog, this.engineModel())
+ }
+
+ /** Only Codex has a verified native path-input contract in this daemon. Keep
+ * the capability gate here so an unknown or non-visual model still receives
+ * the textual path and honest guidance, never an unsupported image request. */
+ private nativeImagePaths(paths: readonly string[]): readonly string[] {
+ if (this.engine !== 'codex' || this.visionCapability() !== 'supported') return []
+ return [...new Set(paths.filter((path) => path.length > 0 && isAbsolute(path)))]
}
/** Advance this agent's read cursor over the conversations it just saw, so a
@@ -3018,6 +3206,12 @@ export class AgentRunner {
}
const latest = rows[rows.length - 1]
if (!latest.id || latest.id === this.lastSteeredMsgId) return // dedup repeated wakes for the same ping
+ const hasImage = normalizeAttachments(latest.attachments ?? latest.attachment).some(isImageAttachment)
+ if (hasImage) {
+ this.lastSteeredMsgId = latest.id
+ console.log(`[computer] ${this.agent.id} STEER deferred (image attachment will be sent with the next full turn)`)
+ return
+ }
this.lastSteeredMsgId = latest.id
const who = latest.author_name ?? 'someone'
const body = (latest.body ?? '').replace(/\s+/g, ' ').slice(0, 300)
@@ -3043,6 +3237,7 @@ export class AgentRunner {
return
}
this.busy = true
+ this.attachmentCache.beginTurn()
let activeBackgroundBrief: WakeBackgroundBrief | null = null
try {
do {
@@ -3081,7 +3276,7 @@ export class AgentRunner {
// superset of what we may ack — a real task that lands during/after
// triage keeps a higher id, stays out of `seen`, and so survives to
// drive the coalesced rerun rather than being silently acked away.
- const { seen, digest, hasReal, projectIds } = await this.snapshotUnread(token)
+ const { seen, digest, hasReal, projectIds, imagePaths } = await this.snapshotUnread(token)
// Which conversation should show "<agent> is typing…"? Prefer the one the
// wake named, but fall back to the unread we just snapshotted, because a
// wake often carries no conversation at all:
@@ -3254,7 +3449,7 @@ export class AgentRunner {
const delta = turnBackgroundBrief
? this.manualBriefDelta(turnBackgroundBrief, memoryDigest, digest, roster)
: this.chatDelta(memoryDigest, triageNote, digest, roster)
- const result = await this.runWithSessionRecovery(delta)
+ const result = await this.runWithSessionRecovery(delta, imagePaths)
exitCode = result.exitCode
turnUsage = result.usage
turnModel = result.model
@@ -3373,6 +3568,9 @@ export class AgentRunner {
console.error(`[computer] ${this.agent.id} turn aborted (will retry on next wake/poll):`,
err instanceof Error ? err.message : err)
} finally {
+ await this.attachmentCache.endTurn().catch((error) => {
+ console.warn(`[computer] ${this.agent.id} attachment cache sweep failed`, error)
+ })
this.busy = false
}
}
@@ -3639,7 +3837,7 @@ async function doRun(serverOverride?: string): Promise<void> {
for (const [id, runner] of runners) {
if (!live.has(id)) {
runners.delete(id)
- await runner.stop({ forceEngine: true })
+ await runner.stop({ forceEngine: true, purgeAttachments: true })
}
}
}
diff --git a/server/src/agents/computer/engine.ts b/server/src/agents/computer/engine.ts
index cf95f72..6338d98 100644
--- a/server/src/agents/computer/engine.ts
+++ b/server/src/agents/computer/engine.ts
@@ -27,12 +27,13 @@ import { randomUUID } from 'node:crypto'
import { existsSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { access, lstat, mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises'
import { homedir, tmpdir } from 'node:os'
-import { dirname, join, delimiter as PATH_DELIMITER } from 'node:path'
+import { dirname, isAbsolute, join, relative, sep, delimiter as PATH_DELIMITER } from 'node:path'
import { StringDecoder } from 'node:string_decoder'
import { stripLoneSurrogates } from '../text-safety.js'
import { CLAUDE_CORE_ENV_KEYS, claudeProviderFingerprint, isCustomAnthropicEndpoint, readClaudeUserSettings, withClaudeUserSettingsEnv } from './claude-user-settings.js'
import { isCliVersionAtLeast, probeEngineVersion, probeLocalEngineVersionWithRetry, versionCommandInvocation } from './cli-version.js'
import { discoverEngineModelCatalog, type EngineModelCatalog } from './model-catalog.js'
+import { visionCapabilityForModel } from './model-capabilities.js'
import { CODEX_RUNTIME_CONFIG_ARGS, codexAuthFingerprint, codexRuntimeEnv } from './codex-runtime.js'
import { cachedCodexProvider, codexProviderEnv, codexProviderFingerprint, codexProviderRuntime, prepareCodexProvider } from './codex-provider.js'
import { assertCodexProviderTransport, codexCommandInvocation } from './codex-rpc.js'
@@ -305,6 +306,27 @@ const TURN_TIMEOUT_MS = Number(process.env.CUMORA_TURN_TIMEOUT_MS) || 0
// fire-hose the daemon doesn't need. Set CUMORA_CODEX_VERBOSE=1 to dump it raw.
const CODEX_LOG_RAW = process.env.CUMORA_CODEX_VERBOSE === '1'
+function codexLocalImagePaths(home: string, localImages: readonly string[]): string[] {
+ let realHome: string
+ try { realHome = realpathSync(home) } catch { return [] }
+ return [...new Set(localImages.filter((path) => {
+ if (!path || !isAbsolute(path)) return false
+ try {
+ const actual = realpathSync(path)
+ const fromHome = relative(realHome, actual)
+ return fromHome !== '' && fromHome !== '..' && !fromHome.startsWith(`..${sep}`) && !isAbsolute(fromHome)
+ } catch { return false }
+ }))]
+}
+
+function codexTurnInput(prompt: string, localImages: readonly string[], home: string): Array<Record<string, unknown>> {
+ const images = codexLocalImagePaths(home, localImages)
+ return [
+ { type: 'text', text: stripLoneSurrogates(prompt), text_elements: [] },
+ ...images.map((path) => ({ type: 'localImage', path })),
+ ]
+}
+
/** How to spawn a CLI bin cross-platform.
* - POSIX: spawn the bare bin with shell:false — unchanged, zero-risk.
* - Windows: engine CLIs are usually `.cmd` shims that Node CANNOT run with
@@ -324,8 +346,10 @@ const CODEX_LOG_RAW = process.env.CUMORA_CODEX_VERBOSE === '1'
// needs a stable handle to the resolver without going through spawn().
export function resolveSpawn(bin: string, env: NodeJS.ProcessEnv = process.env): { command: string; shell: boolean; wantsStdinPrompt: boolean } {
if (!IS_WIN) return { command: bin, shell: false, wantsStdinPrompt: false }
- const exts = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').map((e) => e.trim()).filter(Boolean)
- for (const dir of (env.PATH ?? '').split(PATH_DELIMITER)) {
+ const pathExt = env.PATHEXT ?? env.PathExt ?? '.COM;.EXE;.BAT;.CMD'
+ const searchPath = env.PATH ?? env.Path ?? ''
+ const exts = pathExt.split(';').map((e) => e.trim()).filter(Boolean)
+ for (const dir of searchPath.split(PATH_DELIMITER)) {
if (!dir) continue
for (const ext of exts) {
const candidate = join(dir, bin + ext)
@@ -342,7 +366,7 @@ export function resolveSpawn(bin: string, env: NodeJS.ProcessEnv = process.env):
// itself is a `#!/bin/sh` wrapper and cannot be exec'd without a shell → force
// shell:true so Node routes the call through cmd.exe, which can find the
// .cmd via PATHEXT after the shim.
- for (const dir of (env.PATH ?? '').split(PATH_DELIMITER)) {
+ for (const dir of searchPath.split(PATH_DELIMITER)) {
if (!dir) continue
const shim = join(dir, bin)
if (existsSync(shim)) {
@@ -560,6 +584,12 @@ export interface EngineRunArgs {
* (e.g. a counting relay: it knows it already said "2") instead of
* re-deriving everything from a frozen inbox snapshot each wake. */
resumeSessionId?: string | null
+ /** Explicitly reported visual capability for the active model. */
+ vision?: 'supported' | 'unsupported' | 'unknown'
+ /** Absolute paths to image attachments already materialized in the agent home.
+ * Only adapters with a verified native image-input protocol consume these;
+ * other adapters continue to receive the textual attachment path. */
+ localImages?: readonly string[]
/** Called for each stdout/stderr line — daemon logs / Phase-2 observability. */
onLog: (line: string) => void
/** Optional per-hop trajectory hook — same shape as EngineSessionArgs.onHopUsage.
@@ -794,6 +824,7 @@ export interface EngineSessionArgs {
* transcript stays small enough for native auto-compaction to keep up. Whether a
* session actually carried it is reported by EngineSession.carriesStandingPrompt. */
standingPrompt?: string | null
+ vision?: 'supported' | 'unsupported' | 'unknown'
onLog: (line: string) => void
/** Fire-and-forget per-hop trajectory report. Called once per assistant
* message (Claude) / per turn-completed event (Codex) with that hop's own
@@ -811,7 +842,7 @@ export interface EngineSessionArgs {
export interface EngineSession {
/** Feed ONE turn; resolves when the engine emits its turn `result`. The daemon
* serializes calls (one turn at a time). */
- send(prompt: string): Promise<EngineRunResult>
+ send(prompt: string, localImages?: readonly string[]): Promise<EngineRunResult>
/** Same-turn steering: inject a message into the RUNNING turn at the next safe
* stream-json boundary so the agent answers a direct ping mid-task, then
* continues. No-op if no turn is in flight. */
@@ -2082,16 +2113,17 @@ class CodexSession implements EngineSession {
// reports the real cause instead of a generic "process gone".
private sessionError: string | null = null
private pending: { resolve: (r: EngineRunResult) => void } | null = null
- private queuedPrompt: string | null = null
+ private queuedInput: { prompt: string; localImages: readonly string[] } | null = null
private activeTurnId: string | null = null
private steerGate = false
private readonly model: string | null
+ private readonly vision: EngineSessionArgs['vision']
readonly carriesStandingPrompt: boolean
// Codex reports a RUNNING thread token total; per-turn usage is the delta.
private cum = { input: 0, cached: 0, output: 0 }
private turnStart = { input: 0, cached: 0, output: 0 }
- constructor(bin: string, spawnArgs: string[], home: string, env: NodeJS.ProcessEnv, opts: EngineSessionArgs, providerChanged: () => boolean) {
+ constructor(bin: string, spawnArgs: string[], private readonly home: string, env: NodeJS.ProcessEnv, opts: EngineSessionArgs, providerChanged: () => boolean) {
this.providerChanged = providerChanged
this.authHome = env.CODEX_HOME!
this.authFingerprint = codexAuthFingerprint(this.authHome)
@@ -2099,6 +2131,7 @@ class CodexSession implements EngineSession {
this.onHopUsage = opts.onHopUsage
this.threadId = opts.resumeSessionId ?? null
this.model = opts.model ?? null
+ this.vision = opts.vision
this.carriesStandingPrompt = !!opts.standingPrompt
// experimentalRawEvents → Codex emits payload-free `rawResponseItem/*` pings we
// use as a liveness signal; we suppress them from the log below.
@@ -2146,19 +2179,20 @@ class CodexSession implements EngineSession {
}
get sessionId(): string | null { return this.threadId }
- send(prompt: string): Promise<EngineRunResult> {
+ send(prompt: string, localImages: readonly string[] = []): Promise<EngineRunResult> {
if (this.pending) return Promise.resolve(classifyEngineResult({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.threadId }, this.threadWasResume))
if (!this.alive) return Promise.resolve(classifyEngineResult({ exitCode: this.exitCode || 1, error: this.sessionError ?? 'engine session is not alive (process gone)', sessionId: this.threadId }, this.threadWasResume))
// Only the first turn inherits output from process startup. Later turns
// must not classify an old turn's stderr as their own failure.
if (this.hasSent) this.stderrTail = ''
this.hasSent = true
+ const input = { prompt, localImages: [...localImages] }
return new Promise<EngineRunResult>((resolve) => {
this.pending = { resolve }
this.turnStart = { ...this.cum }
// Fire now if the thread handshake already completed; else queue until it does.
- if (this.ready && this.threadId) this.startTurn(prompt)
- else this.queuedPrompt = prompt
+ if (this.ready && this.threadId) this.startTurn(input)
+ else this.queuedInput = input
})
}
@@ -2183,10 +2217,13 @@ class CodexSession implements EngineSession {
private notify(method: string, params: Record<string, unknown>): void {
writeStdin(this.child, JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n')
}
- private startTurn(prompt: string): void {
+ private startTurn(input: { prompt: string; localImages: readonly string[] }): void {
if (this.threadId) {
this.turnStartedAt = Date.now()
- this.req('turn/start', { threadId: this.threadId, input: [{ type: 'text', text: stripLoneSurrogates(prompt) }] })
+ this.req('turn/start', {
+ threadId: this.threadId,
+ input: codexTurnInput(input.prompt, this.vision === 'supported' ? input.localImages : [], this.home),
+ })
}
}
@@ -2302,7 +2339,11 @@ class CodexSession implements EngineSession {
this.threadId = threadId
this.threadWasResume = false
this.ready = true
- if (this.queuedPrompt && this.pending) { const p = this.queuedPrompt; this.queuedPrompt = null; this.startTurn(p) }
+ if (this.queuedInput && this.pending) {
+ const input = this.queuedInput
+ this.queuedInput = null
+ this.startTurn(input)
+ }
}
private updateUsage(total: unknown): void {
@@ -2518,14 +2559,22 @@ class CodexAdapter implements EngineAdapter {
: [...codexSecureExecArgs(args), '--skip-git-repo-check']
if (!base.includes('--json')) base.push('--json')
const model = args.model ? ['--model', args.model] : []
- const resume = args.resumeSessionId ? ['resume', args.resumeSessionId] : []
+ const imageArgs = args.vision === 'supported'
+ ? codexLocalImagePaths(args.home, args.localImages ?? []).flatMap((path) => ['--image', path])
+ : []
+ // `resume` owns its own positional session id and --image option. Keep the
+ // option before the id so clap cannot mistake it for the prompt argument.
+ const resume = args.resumeSessionId
+ ? ['resume', ...imageArgs, args.resumeSessionId]
+ : []
+ const freshImages = args.resumeSessionId ? [] : imageArgs
const { command, shell, argsPrefix } = resolveCodexSpawn()
let sessionId = args.resumeSessionId ?? null
assertCodexProviderTransport(provider.args, shell)
let usage: EngineUsage | undefined
let turnError: string | undefined
const started = Date.now()
- return spawnEngine(command, [...argsPrefix, ...provider.args, ...base, ...model, ...CODEX_RUNTIME_CONFIG_ARGS, ...codexServiceTierArgs(args.nativeFastMode ?? false), ...resume, '-'], args, {
+ return spawnEngine(command, [...argsPrefix, ...provider.args, ...base, ...freshImages, ...model, ...CODEX_RUNTIME_CONFIG_ARGS, ...codexServiceTierArgs(args.nativeFastMode ?? false), ...resume, '-'], args, {
shell, stdinText: args.prompt,
onStdoutLine(line) {
let event
@@ -2582,7 +2631,8 @@ class CodexAdapter implements EngineAdapter {
/** Official Grok Build install lives at ~/.grok/bin even when that dir is
* not on the daemon's PATH (launchd / login-shell mismatch). PATH wins. */
function resolveGrokBin(env: NodeJS.ProcessEnv = process.env): string | null {
- for (const dir of (env.PATH ?? '').split(PATH_DELIMITER)) {
+ const searchPath = env.PATH ?? env.Path ?? ''
+ for (const dir of searchPath.split(PATH_DELIMITER)) {
if (!dir) continue
const candidate = join(dir, IS_WIN ? 'grok.exe' : 'grok')
if (existsSync(candidate)) return candidate
@@ -2859,14 +2909,14 @@ class GrokAdapter implements EngineAdapter {
readonly bin = 'grok'
private command(env?: NodeJS.ProcessEnv): string {
- return resolveGrokBin(env) ?? this.bin
+ return resolveGrokBin(env) ?? resolveSpawn(this.bin, env).command
}
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
const flags = extraArgs('CUMORA_TRIAGE_ARGS')
const model = ['--model', args.model || 'grok-4.5']
const command = this.command(args.env)
- const { shell, wantsStdinPrompt } = resolveSpawn(this.bin)
+ const { shell, wantsStdinPrompt } = resolveSpawn(this.bin, args.env)
const usingJson = flags.length === 0
const base = flags.length
? [...flags, '-p']
@@ -2895,7 +2945,7 @@ class GrokAdapter implements EngineAdapter {
probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
const model = args.tier === 'small' ? ['--model', 'grok-4.5'] : []
const command = this.command(args.env)
- const { shell, wantsStdinPrompt } = resolveSpawn(this.bin)
+ const { shell, wantsStdinPrompt } = resolveSpawn(this.bin, args.env)
const base = ['-p', ...model, '--output-format', 'json', '--always-approve', '--no-auto-update']
const argv = wantsStdinPrompt ? base : ['-p', DOCTOR_PROMPT, ...base.slice(1)]
return spawnCapture(command, argv, {
@@ -2996,7 +3046,7 @@ class GrokAdapter implements EngineAdapter {
const model = args.model ? ['--model', args.model] : []
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
const command = this.command(args.env)
- const { shell, wantsStdinPrompt } = resolveSpawn(this.bin)
+ const { shell, wantsStdinPrompt } = resolveSpawn(this.bin, args.env)
const base = flags.length
? [...flags, ...resume, '-p']
: ['-p', ...resume, ...model, '--output-format', 'streaming-messages-json', '--always-approve', '--no-auto-update']
@@ -6807,6 +6857,15 @@ export async function enrichDetectedEngines(
}))
}
+/** Resolve the active model's visuals from the account-specific catalog. A
+ * default model inherits the catalog default; a custom pin is looked up by id. */
+export function engineVisionCapability(
+ catalog: Pick<EngineModelCatalog, 'models' | 'defaultModel'> | null | undefined,
+ modelId: string | null | undefined,
+): 'supported' | 'unsupported' | 'unknown' {
+ return visionCapabilityForModel(catalog, modelId || catalog?.defaultModel || null)
+}
+
/** Resolve a bin's absolute path on PATH (the first hit), or null if absent. */
export async function resolveBinPath(bin: string): Promise<string | null> {
return new Promise((resolve) => {
diff --git a/server/src/agents/computer/model-capabilities.ts b/server/src/agents/computer/model-capabilities.ts
new file mode 100644
index 0000000..86f0239
--- /dev/null
+++ b/server/src/agents/computer/model-capabilities.ts
@@ -0,0 +1,39 @@
+import type { EngineId } from './engine.js'
+import type { EngineModelCatalog } from './model-catalog.js'
+
+/** A model capability is deliberately tri-state. An absent provider claim is
+ * not evidence that an image can be read, and it is not evidence that it
+ * cannot. Callers must surface the unknown state instead of silently dropping
+ * an image or pretending it was understood. */
+export type VisionCapability = 'supported' | 'unsupported' | 'unknown'
+
+export interface EngineCapabilities {
+ engine: EngineId
+ /** Secure engines keep model file access inside the approved agent home.
+ * Compatibility engines are opt-in and retain their existing host policy. */
+ filesystem: 'sandboxed' | 'compatibility'
+ /** The daemon can materialize chat attachments into the agent home for every
+ * engine, so attachment access does not depend on host-home permissions. */
+ attachmentAccess: 'daemon-cache'
+ vision: VisionCapability
+}
+
+export function visionCapabilityForModel(
+ catalog: Pick<EngineModelCatalog, 'models'> | null | undefined,
+ modelId: string | null | undefined,
+): VisionCapability {
+ if (!catalog || !modelId) return 'unknown'
+ return catalog.models.find((model) => model.id === modelId)?.vision ?? 'unknown'
+}
+
+export function engineCapabilities(
+ engine: EngineId,
+ opts: { unsandboxed?: boolean; vision?: VisionCapability } = {},
+): EngineCapabilities {
+ return {
+ engine,
+ filesystem: opts.unsandboxed ? 'compatibility' : 'sandboxed',
+ attachmentAccess: 'daemon-cache',
+ vision: opts.vision ?? 'unknown',
+ }
+}
diff --git a/server/src/agents/computer/model-catalog.ts b/server/src/agents/computer/model-catalog.ts
index ad8329c..01f076b 100644
--- a/server/src/agents/computer/model-catalog.ts
+++ b/server/src/agents/computer/model-catalog.ts
@@ -10,6 +10,7 @@ import { configuredEngineModels } from './configured-models.js'
import type { EngineId } from './engine.js'
import { modelIdOrNull } from './model-id.js'
import { fetchProviderModels, MAX_CATALOG_MODELS, readProviderCatalogFile } from './provider-models.js'
+import type { VisionCapability } from './model-capabilities.js'
export type ModelCatalogSource = 'protocol' | 'cli' | 'presets'
export type FastModelScope = 'agent' | 'computer' | 'unsupported'
@@ -20,6 +21,8 @@ export interface EngineModelOption {
description?: string | null
recommendedFor?: Array<'big' | 'small'>
supportsFastMode?: boolean
+ /** Explicitly reported vision support. Missing means unknown. */
+ vision?: VisionCapability
}
/** Model choices advertised by the daemon that actually owns the CLI login.
@@ -210,6 +213,9 @@ function mergeModels(discovered: EngineModelOption[], fallback: EngineModelOptio
description: clean(model.description, 320),
recommendedFor: model.recommendedFor?.filter((tier): tier is 'big' | 'small' => tier === 'big' || tier === 'small'),
...(typeof model.supportsFastMode === 'boolean' ? { supportsFastMode: model.supportsFastMode } : {}),
+ ...(model.vision === 'supported' || model.vision === 'unsupported' || model.vision === 'unknown'
+ ? { vision: model.vision }
+ : {}),
})
if (out.length >= MAX_CATALOG_MODELS) break
}
@@ -390,6 +396,9 @@ interface CodexListItem {
description?: unknown
isDefault?: unknown
serviceTiers?: unknown
+ input_modalities?: unknown
+ inputModalities?: unknown
+ input?: unknown
}
async function discoverCodex(command: string, env: NodeJS.ProcessEnv, providerArgs: string[]): Promise<{ models: EngineModelOption[]; defaultModel: string | null } | null> {
@@ -409,8 +418,16 @@ async function discoverCodex(command: string, env: NodeJS.ProcessEnv, providerAr
for (const row of result.data as CodexListItem[]) {
const id = modelIdOrNull(typeof row.model === 'string' ? row.model : typeof row.id === 'string' ? row.id : null)
if (!id) continue
+ const modalities = Array.isArray(row.input_modalities)
+ ? row.input_modalities
+ : Array.isArray(row.inputModalities)
+ ? row.inputModalities
+ : row.input && typeof row.input === 'object' && Array.isArray((row.input as { modalities?: unknown }).modalities)
+ ? (row.input as { modalities: unknown[] }).modalities
+ : null
models.push({ id, label: clean(row.displayName, 160) ?? id, description: clean(row.description, 320),
recommendedFor: row.isDefault === true ? ['big'] : undefined,
+ ...(modalities ? { vision: modalities.includes('image') ? 'supported' as const : 'unsupported' as const } : {}),
...(Array.isArray(row.serviceTiers) ? {
supportsFastMode: row.serviceTiers.some((tier) => tier?.id === 'fast' || tier?.id === 'priority'),
} : {}),
diff --git a/server/src/agents/computer/registry.ts b/server/src/agents/computer/registry.ts
index 0dcc7e4..5175d33 100644
--- a/server/src/agents/computer/registry.ts
+++ b/server/src/agents/computer/registry.ts
@@ -205,6 +205,9 @@ function sanitizeModelCatalog(raw: unknown): EngineModelCatalog | undefined {
description: displayString(model.description, 320),
...(recommendedFor?.length ? { recommendedFor } : {}),
...(typeof model.supportsFastMode === 'boolean' ? { supportsFastMode: model.supportsFastMode } : {}),
+ ...(model.vision === 'supported' || model.vision === 'unsupported' || model.vision === 'unknown'
+ ? { vision: model.vision }
+ : {}),
})
}
}
@@ -765,7 +768,7 @@ export async function mintAgentRuntimeToken(args: {
* provider can explicitly make its unnamed local default authoritative so a
* vendor-specific deploy pin never crosses into the wrong namespace. */
export async function listAgentsForComputer(computerId: string, supportsProviderProfiles = false): Promise<
- Array<{ id: string; name: string; role: string | null; systemPrompt: string | null; engine: EngineId | null; model: string | null; fastModel: string | null; providerProfile: string | null; nativeFastMode: boolean }>
+ Array<{ id: string; name: string; role: string | null; systemPrompt: string | null; engine: EngineId | null; model: string | null; fastModel: string | null; providerProfile: string | null; nativeFastMode: boolean; modelCatalog?: EngineModelCatalog }>
> {
const { rows } = await pool.query<{
id: string; name: string; role: string | null; systemPrompt: string | null
@@ -800,11 +803,11 @@ export async function listAgentsForComputer(computerId: string, supportsProvider
const ompDefault = process.env.CUMORA_DEFAULT_OMP_MODEL?.trim() || null
return rows.map((r) => {
const { availableEngines, detectedEngines, engineDefaults, ...agent } = r
- // A profile's endpoint owns its model namespace: neither the computer's
- // engine_defaults nor the deploy-level pin may name a model for it.
- if (agent.providerProfile) return agent
const localCatalog = sanitizeDetectedEngines(detectedEngines, availableEngines ?? [])
.find((entry) => entry.id === agent.engine)?.modelCatalog
+ // A profile's endpoint owns its model namespace: neither the computer's
+ // engine_defaults nor the deploy-level pin may name a model for it.
+ if (agent.providerProfile) return { ...agent, ...(localCatalog ? { modelCatalog: localCatalog } : {}) }
// Parse the engine_defaults JSONB
const defaults = (engineDefaults && typeof engineDefaults === 'object'
? engineDefaults as EngineDefaultsMap
@@ -815,6 +818,7 @@ export async function listAgentsForComputer(computerId: string, supportsProvider
if (localCatalog?.prefersLocalDefault) {
return {
...agent,
+ ...(localCatalog ? { modelCatalog: localCatalog } : {}),
model: agent.model ?? engineDefaultsForAgent?.model ?? null,
fastModel: agent.fastModel ?? engineDefaultsForAgent?.fastModel ?? null,
}
@@ -823,7 +827,7 @@ export async function listAgentsForComputer(computerId: string, supportsProvider
const modelWithEngineDefault = agent.model ?? engineDefaultsForAgent?.model ?? null
const fastModelWithEngineDefault = agent.fastModel ?? engineDefaultsForAgent?.fastModel ?? null
if (modelWithEngineDefault) {
- return { ...agent, model: modelWithEngineDefault, fastModel: fastModelWithEngineDefault }
+ return { ...agent, ...(localCatalog ? { modelCatalog: localCatalog } : {}), model: modelWithEngineDefault, fastModel: fastModelWithEngineDefault }
}
const dflt = r.engine === 'codex'
? codexDefault
@@ -850,7 +854,9 @@ export async function listAgentsForComputer(computerId: string, supportsProvider
: r.engine === 'omp'
? ompDefault
: null
- return dflt ? { ...agent, model: dflt, fastModel: fastModelWithEngineDefault } : { ...agent, fastModel: fastModelWithEngineDefault }
+ return dflt
+ ? { ...agent, ...(localCatalog ? { modelCatalog: localCatalog } : {}), model: dflt, fastModel: fastModelWithEngineDefault }
+ : { ...agent, ...(localCatalog ? { modelCatalog: localCatalog } : {}), fastModel: fastModelWithEngineDefault }
})
}
diff --git a/server/src/agents/runtime/authorization.ts b/server/src/agents/runtime/authorization.ts
index ba99545..486a560 100644
--- a/server/src/agents/runtime/authorization.ts
+++ b/server/src/agents/runtime/authorization.ts
@@ -1,5 +1,6 @@
import type { PoolClient } from 'pg'
import { pool } from '../../db/pool.js'
+import { storageKeyFromPublicUrl } from '../../storage.js'
import type { AgentRuntimeClaims } from './jwt.js'
/**
@@ -31,6 +32,13 @@ export async function isRuntimeAgentAuthorized(
return rowCount === 1
}
+/** Legacy rows may not cache a storage key. Derive one only through the same
+ * configured-origin parser used when serving that row; arbitrary URLs from a
+ * message can never authorize an attachment read. */
+export function attachmentUrlMatchesStorageKey(url: string, key: string): boolean {
+ return storageKeyFromPublicUrl(url) === key
+}
+
/** Hold the live runtime identity and every referenced run stable through an
* observability mutation. Participant reassignment/offboarding updates
* conflict with FOR SHARE; run GC and competing run mutations conflict with
@@ -194,3 +202,114 @@ export async function withRuntimeMessageReadAuthorization<T>(args: {
client.release()
}
}
+
+/** Authorize an attachment object only when it is referenced by a message the
+ * runtime agent can currently read. The storage key is a selector; membership
+ * and tenant are the authority. */
+export async function withRuntimeAttachmentReadAuthorization(args: {
+ agentId: string
+ companyId: string
+ key: string
+ /** When supplied, the exact message must also currently be readable. */
+ messageId?: string
+}): Promise<boolean> {
+ const client = await pool.connect()
+ try {
+ await client.query('BEGIN')
+ const participant = await client.query(
+ `SELECT id FROM participants
+ WHERE id = $1 AND company_id = $2
+ AND kind = 'agent' AND departed_at IS NULL
+ FOR SHARE`,
+ [args.agentId, args.companyId],
+ )
+ if (!participant.rowCount) {
+ await client.query('ROLLBACK')
+ return false
+ }
+ const allowed = await client.query(
+ `SELECT 1
+ FROM messages m
+ JOIN conversations c
+ ON c.id = m.conversation_id AND c.company_id = m.company_id
+ WHERE m.company_id = $1
+ AND ($4::text IS NULL OR m.id = $4)
+ AND (
+ EXISTS (
+ SELECT 1 FROM conversation_members cm
+ WHERE cm.conversation_id = c.id
+ AND cm.company_id = c.company_id
+ AND cm.participant_id = $2
+ )
+ OR (m.kind = 'system' AND m.delivery_recipient_id = $2)
+ )
+ AND (
+ m.attachment->>'key' = $3
+ OR EXISTS (
+ SELECT 1
+ FROM jsonb_array_elements(
+ CASE WHEN jsonb_typeof(m.attachments) = 'array'
+ THEN m.attachments ELSE '[]'::jsonb END
+ ) attachment
+ WHERE attachment->>'key' = $3
+ )
+ )
+ AND EXISTS (
+ SELECT 1 FROM attachment_grants ag
+ WHERE ag.storage_key = $3
+ AND ag.company_id = $1
+ AND ag.status = 'active'
+ )
+ LIMIT 1
+ FOR SHARE OF c, m`,
+ [args.companyId, args.agentId, args.key, args.messageId ?? null],
+ )
+ if (allowed.rowCount) {
+ await client.query('COMMIT')
+ return true
+ }
+
+ // Older rows predate persisted storage keys. Re-signing derives their key
+ // from the URL, so authorization must accept the same legacy reference.
+ // Narrow in SQL to rows whose URL contains this unguessable key, then apply
+ // the configured-origin parser before authorizing the fetch.
+ const legacy = await client.query<{ attachment: { url?: unknown } | null }>(
+ `SELECT m.attachment
+ FROM messages m
+ JOIN conversations c
+ ON c.id = m.conversation_id AND c.company_id = m.company_id
+ WHERE m.company_id = $1
+ AND ($4::text IS NULL OR m.id = $4)
+ AND jsonb_typeof(m.attachment) = 'object'
+ AND strpos(COALESCE(m.attachment->>'url', ''), $3) > 0
+ AND EXISTS (
+ SELECT 1 FROM attachment_grants ag
+ WHERE ag.storage_key = $3
+ AND ag.company_id = $1
+ AND ag.status = 'active'
+ )
+ AND (
+ EXISTS (
+ SELECT 1 FROM conversation_members cm
+ WHERE cm.conversation_id = c.id
+ AND cm.company_id = c.company_id
+ AND cm.participant_id = $2
+ )
+ OR (m.kind = 'system' AND m.delivery_recipient_id = $2)
+ )
+ LIMIT 200`,
+ [args.companyId, args.agentId, args.key, args.messageId ?? null],
+ )
+ const derived = legacy.rows.some((row) => {
+ const url = row.attachment?.url
+ return typeof url === 'string' && attachmentUrlMatchesStorageKey(url, args.key)
+ })
+ await client.query(derived ? 'COMMIT' : 'ROLLBACK')
+ return derived
+ } catch (error) {
+ await client.query('ROLLBACK').catch(() => {})
+ throw error
+ } finally {
+ client.release()
+ }
+}
diff --git a/server/src/agents/runtime/client.ts b/server/src/agents/runtime/client.ts
index ecc1406..d4c0105 100644
--- a/server/src/agents/runtime/client.ts
+++ b/server/src/agents/runtime/client.ts
@@ -37,6 +37,7 @@ export interface InboxAttachment {
name: string
kind: string
mime?: string
+ size?: number
/** Storage key (`attachments/<uuid>.<ext>`) preserved for re-signing. */
key?: string
}
@@ -73,6 +74,9 @@ export interface InboxRow {
sequence: number
created_at: string
attachment: InboxAttachment | null
+ /** Canonical ordered list. `attachment` remains the first-entry projection
+ * for older runtime consumers. */
+ attachments?: InboxAttachment[]
/** Set when this message is a reply: id of the message it quotes. */
quoted_message_id: string | null
/** Inline summary of the quoted-original so the agent turn sees both the
diff --git a/server/src/agents/runtime/inproc-client.ts b/server/src/agents/runtime/inproc-client.ts
index 8057119..c4e5ef1 100644
--- a/server/src/agents/runtime/inproc-client.ts
+++ b/server/src/agents/runtime/inproc-client.ts
@@ -20,7 +20,7 @@ import { pool } from '../../db/pool.js'
import { CH_MESSAGE_NEW, CH_TYPING, publish, redis } from '../../redis.js'
import { enqueueBroadcast, nudgeRealtimeOutbox } from '../../realtime-outbox.js'
import { notifyAlert } from '../../alerting.js'
-import { freshenAttachmentUrl, type StoredAttachment } from '../../storage.js'
+import { freshenMessageAttachments } from '../../storage.js'
/** Re-sign attachment download URLs just-in-time when loading messages for an
* agent turn. The url stored in `messages.attachment` is signed with a TTL
@@ -29,12 +29,12 @@ import { freshenAttachmentUrl, type StoredAttachment } from '../../storage.js'
* link — the HMAC has expired → 403 → "can't see the image". Re-sign each row's
* attachment so every consumer gets a URL valid for a fresh TTL. Best-effort:
* freshenAttachmentUrl keeps the stored url on any failure. */
-async function refreshAttachmentUrls(rows: ReadonlyArray<{ attachment?: unknown }>): Promise<void> {
+async function refreshAttachmentUrls(rows: ReadonlyArray<{ attachment?: unknown; attachments?: unknown }>): Promise<void> {
await Promise.all(rows.map(async (r) => {
- const a = r.attachment as StoredAttachment | null | undefined
- if (!a || typeof a !== 'object' || !a.url) return
+ const stored = r.attachments ?? r.attachment
+ if (!stored) return
try {
- ;(r as { attachment?: unknown }).attachment = await freshenAttachmentUrl(a)
+ Object.assign(r, await freshenMessageAttachments(stored))
} catch { /* keep the stored (possibly stale) url */ }
}))
}
@@ -189,7 +189,11 @@ export class InProcRuntimeClient implements AgentRuntimeClient {
co.conversation_title, co.conversation_kind, co.conversation_topic,
co.project_id, co.project_name,
m.author_id, p.kind AS author_kind, COALESCE(p.name, m.author_id) AS author_name,
- m.body, m.kind, m.sequence, m.created_at, m.attachment, m.quoted_message_id,
+ m.body, m.kind, m.sequence, m.created_at,
+ COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
+ ELSE jsonb_build_array(m.attachment) END) AS attachments,
+ COALESCE(m.attachments->0, m.attachment) AS attachment,
+ m.quoted_message_id,
(
SELECT jsonb_build_object(
'id', qm.id, 'authorId', qm.author_id,
@@ -381,7 +385,11 @@ export class InProcRuntimeClient implements AgentRuntimeClient {
recent AS (
SELECT
m.id, m.conversation_id, m.author_id, m.kind, m.body, m.sequence,
- m.created_at, m.attachment, m.quoted_message_id,
+ m.created_at,
+ COALESCE(m.attachments, CASE WHEN m.attachment IS NULL THEN '[]'::jsonb
+ ELSE jsonb_build_array(m.attachment) END) AS attachments,
+ COALESCE(m.attachments->0, m.attachment) AS attachment,
+ m.quoted_message_id,
c.company_id,
c.title AS conversation_title, c.kind AS conversation_kind, c.topic AS conversation_topic,
pr.name AS project_name,
@@ -428,7 +436,8 @@ export class InProcRuntimeClient implements AgentRuntimeClient {
)
SELECT id, conversation_id, company_id, conversation_title, conversation_kind, conversation_topic,
project_name,
- author_id, author_kind, author_name, body, kind, sequence, created_at, attachment,
+ author_id, author_kind, author_name, body, kind, sequence, created_at,
+ attachment, attachments,
quoted_message_id, human_last_read_at,
(
SELECT jsonb_build_object(
diff --git a/server/src/agents/runtime/server.ts b/server/src/agents/runtime/server.ts
index bb3d3bd..8ef0451 100644
--- a/server/src/agents/runtime/server.ts
+++ b/server/src/agents/runtime/server.ts
@@ -35,6 +35,7 @@ import { consumeAgentTurnToken } from '../scheduler.js'
import {
isRuntimeAgentAuthorized,
withRuntimeAgentRunAuthorization,
+ withRuntimeAttachmentReadAuthorization,
withRuntimeConversationAuthorization,
withRuntimeMessageReadAuthorization,
} from './authorization.js'
@@ -45,6 +46,8 @@ import { attachFsEndpoints } from './fs-endpoints.js'
import { inprocClient } from './inproc-client.js'
import { type AgentRuntimeClaims, verifyAgentToken } from './jwt.js'
import { attachWakeStream, } from './wake-bus.js'
+import { normalizeStorageKey } from '../../storage-keys.js'
+import { storage } from '../../storage.js'
export type { WakeEvent } from './wake-bus.js'
@@ -183,6 +186,7 @@ runtimeRouter.post('/cli', withAgent(async (c, req, res) => {
exitCode: result.exitCode,
ok: result.ok,
sideEffects: result.sideEffects ?? [],
+ attachmentReads: result.attachmentReads ?? [],
})
}))
@@ -224,6 +228,37 @@ runtimeRouter.get('/inbox', withAgent(async (c, req, res) => {
res.json({ rows })
}))
+// BYOA engines use this authenticated endpoint instead of a raw storage URL.
+// The object must be both a Cumora chat attachment and referenced by a message
+// this exact runtime placement can read. The server redirects to a freshly
+// generated storage URL; callers cannot select an arbitrary fetch target.
+runtimeRouter.get('/attachment', withAgent(async (c, req, res) => {
+ const key = normalizeStorageKey(typeof req.query.key === 'string' ? req.query.key : '')
+ const messageId = typeof req.query.messageId === 'string' && req.query.messageId
+ ? req.query.messageId
+ : undefined
+ if (!key?.startsWith('attachments/')) {
+ res.status(400).json({ error: 'invalid chat attachment key' })
+ return
+ }
+ if (!(await withRuntimeAttachmentReadAuthorization({
+ agentId: c.sub,
+ companyId: c.companyId,
+ key,
+ messageId,
+ }))) {
+ res.status(403).json({ error: 'attachment is not readable by this agent' })
+ return
+ }
+ const metadata = await storage.statObject(key)
+ if (!metadata) {
+ res.status(404).json({ error: 'attachment not found' })
+ return
+ }
+ res.setHeader('Cache-Control', 'private, no-store')
+ res.redirect(303, await storage.publicUrl(key))
+}))
+
// BYOA: build the triage request server-side (we have the DB for inbox+context)
// but DON'T run the model — return either an empty-inbox verdict (nothing to
// judge) or the {instructions, input} prompt. The daemon runs it on its LOCAL
diff --git a/server/src/agents/turn.ts b/server/src/agents/turn.ts
index b27c6b5..3d4a5ae 100644
--- a/server/src/agents/turn.ts
+++ b/server/src/agents/turn.ts
@@ -22,6 +22,7 @@ import { env } from '../env.js'
import { redis } from '../redis.js'
import { readLocalMessageAttachment } from '../local-attachment-files.js'
import { messageAttachmentStorageKey } from '../storage-keys.js'
+import { ATTACHMENT_TEXT_EXCERPT_BYTES, normalizeAttachments } from '../../../shared/attachments.js'
import { classifyInboxTriage, gateSyntheticWake } from './inbox-triage.js'
import { GLANCE_YIELD_RULES } from './glance-protocol.js'
import { TOOL_DEFS_RESPONSES, executePodTool } from './runtime/pod-tools.js'
@@ -106,6 +107,7 @@ interface InboxRow {
sequence: number
created_at: string
attachment: InboxAttachment | null
+ attachments?: InboxAttachment[]
/** Set when this message is a reply: the id of the quoted-original. */
quoted_message_id: string | null
/** Inlined summary of the quoted-original — saves the agent a second
@@ -662,10 +664,8 @@ function renderContext(
.join(' ')
line += ` ⟨${summary}⟩`
}
- if (m.attachment) {
- const a = m.attachment
- line += ` [attachment: ${a.kind} "${a.name}" ${a.url}]`
- }
+ const messageAttachments = normalizeAttachments(m.attachments ?? m.attachment)
+ for (const a of messageAttachments) line += ` [attachment: ${a.kind} "${a.name}" ${a.url ?? ''}]`
lines.push(line)
// Reply context: render the quoted-original right below so the LLM
// sees BOTH the reply and what it's replying to. `↩ quoting [id]
@@ -681,9 +681,10 @@ function renderContext(
}
// Inline the text-file content below the message line so the LLM
// actually READS the file rather than just noting it exists.
- const excerpt = textExcerpts.get(m.id)
- if (excerpt) {
- lines.push(` ▼ file content (${m.attachment?.name ?? 'attachment'}${excerpt.truncated ? ', truncated' : ''}):`)
+ for (const [index, attachment] of messageAttachments.entries()) {
+ const excerpt = textExcerpts.get(`${m.id}\0${index}`)
+ if (!excerpt) continue
+ lines.push(` ▼ file content (${attachment.name}${excerpt.truncated ? ', truncated' : ''}):`)
lines.push(` \`\`\`${excerpt.lang}`)
for (const ln of excerpt.text.split('\n')) lines.push(` ${ln}`)
lines.push(' ```')
@@ -704,9 +705,9 @@ function renderContext(
* between "an agent NOTICES Alice sent me a config.yaml" and "an agent
* actually READS the config.yaml" — Skype-like behaviour.
*/
-const MAX_TEXT_ATTACHMENT_BYTES = 50_000 // 50 KB per file
const TEXT_LIKE_MIMES = new Set([
- 'application/json', 'application/x-yaml', 'application/x-toml',
+ 'application/json', 'application/x-yaml', 'application/x-toml', 'application/xml',
+ 'application/javascript', 'application/sql',
])
/** Return a short fence language label for a mime, used purely as a hint
@@ -726,7 +727,7 @@ function langFromMime(mime: string, name: string): string {
interface TextExcerpt { lang: string; text: string; truncated: boolean }
-/** Read a single text-like attachment, returning at most MAX_TEXT_ATTACHMENT_BYTES.
+/** Read a single text-like attachment, returning at most 50 KiB.
* Returns null for non-text mimes or fetch failures — callers fall back to
* the "[attachment: file ...]" pointer-only line. */
async function readTextAttachment(att: InboxAttachment): Promise<TextExcerpt | null> {
@@ -758,8 +759,8 @@ async function readTextAttachment(att: InboxAttachment): Promise<TextExcerpt | n
}
}
if (!buf) return null
- const truncated = buf.length > MAX_TEXT_ATTACHMENT_BYTES
- const sliced = truncated ? buf.subarray(0, MAX_TEXT_ATTACHMENT_BYTES) : buf
+ const truncated = buf.length > ATTACHMENT_TEXT_EXCERPT_BYTES
+ const sliced = truncated ? buf.subarray(0, ATTACHMENT_TEXT_EXCERPT_BYTES) : buf
return {
lang: langFromMime(mime, att.name),
text: sliced.toString('utf8'),
@@ -774,10 +775,11 @@ async function loadTextExcerpts(items: InboxRow[]): Promise<Map<string, TextExce
const out = new Map<string, TextExcerpt>()
const work: Array<Promise<void>> = []
for (const m of items) {
- if (!m.attachment) continue
- work.push(readTextAttachment(m.attachment).then((ex) => {
- if (ex) out.set(m.id, ex)
- }))
+ for (const [index, attachment] of normalizeAttachments(m.attachments ?? m.attachment).entries()) {
+ work.push(readTextAttachment(attachment as InboxAttachment).then((ex) => {
+ if (ex) out.set(`${m.id}\0${index}`, ex)
+ }))
+ }
}
await Promise.all(work)
return out
@@ -786,18 +788,34 @@ async function loadTextExcerpts(items: InboxRow[]): Promise<Map<string, TextExce
/** Pull every image attachment out of the inbox so we can pass them as input_image.
* Re-signs URLs just-in-time so OpenAI's fetch from the Worker side doesn't
* hit an expired HMAC. */
-async function collectImageAttachments(items: InboxRow[]): Promise<Array<{ messageId: string; url: string; name: string }>> {
- const out: Array<{ messageId: string; url: string; name: string }> = []
+interface CollectedImageAttachments {
+ images: Array<{ messageId: string; url: string; name: string }>
+ unavailable: Array<{ messageId: string; name: string; reason: string }>
+}
+
+async function collectImageAttachments(items: InboxRow[]): Promise<CollectedImageAttachments> {
+ const out: CollectedImageAttachments = { images: [], unavailable: [] }
for (const m of items) {
- const a = m.attachment
- if (!a || a.kind !== 'img' || !a.url) continue
- const source = await trustedAttachmentSource(a)
- if (!source) continue
- const url = publicUrlFor(source.url)
- // Only ship images OpenAI can actually fetch. Local /uploads paths without
- // a PUBLIC_HOST get textually mentioned but not vision-fed.
- if (!/^https?:\/\//.test(url)) continue
- out.push({ messageId: m.id, url, name: a.name })
+ for (const a of normalizeAttachments(m.attachments ?? m.attachment)) {
+ if (a.kind !== 'img' && a.mime?.startsWith('image/') !== true) continue
+ if (!a.url) {
+ out.unavailable.push({ messageId: m.id, name: a.name, reason: 'the attachment has no download URL' })
+ continue
+ }
+ const source = await trustedAttachmentSource(a as InboxAttachment)
+ if (!source) {
+ out.unavailable.push({ messageId: m.id, name: a.name, reason: 'the image does not reference trusted Cumora storage' })
+ continue
+ }
+ const url = publicUrlFor(source.url)
+ // Only ship images OpenAI can actually fetch. Local /uploads paths without
+ // a PUBLIC_HOST get textually mentioned but not vision-fed.
+ if (!/^https?:\/\//.test(url)) {
+ out.unavailable.push({ messageId: m.id, name: a.name, reason: 'the image is not reachable from this runtime' })
+ continue
+ }
+ out.images.push({ messageId: m.id, url, name: a.name })
+ }
}
return out
}
@@ -972,14 +990,12 @@ function traceInboxMessage(m: InboxRow): Record<string, unknown> {
sequence: m.sequence,
createdAt: m.created_at,
body: traceText(m.body),
- attachment: m.attachment
- ? {
- name: m.attachment.name,
- kind: m.attachment.kind,
- mime: m.attachment.mime,
- url: m.attachment.url,
- }
- : null,
+ attachments: normalizeAttachments(m.attachments ?? m.attachment).map((attachment) => ({
+ name: attachment.name,
+ kind: attachment.kind,
+ mime: attachment.mime,
+ url: attachment.url,
+ })),
quotedMessageId: m.quoted_message_id,
quoted: m.quoted
? {
@@ -2287,7 +2303,7 @@ Mechanics:
// input_image content items so vision-capable models can actually see them.
// (We cast through unknown because the SDK's ResponseInputItem union is
// narrower than the runtime API actually accepts for multimodal content.)
- const images = await collectImageAttachments(inbox)
+ const collectedImages = await collectImageAttachments(inbox)
const userContent: Array<Record<string, unknown>> = [{ type: 'input_text', text: wakePrompt }]
// Materialize every external image URL into a base64 `data:` URL *here*
@@ -2301,7 +2317,7 @@ Mechanics:
// accept the bytes (rare format issues, etc.).
const [faceMats, imageMats] = await Promise.all([
Promise.all(faces.map(async (f) => ({ f, mat: await materializeImage(f.url) }))),
- Promise.all(images.map(async (img) => ({ img, mat: await materializeImage(img.url) }))),
+ Promise.all(collectedImages.images.map(async (img) => ({ img, mat: await materializeImage(img.url) }))),
])
if (faces.length > 0) {
@@ -2323,8 +2339,19 @@ Mechanics:
userContent.push({ type: 'input_text', text: `↳ image attached to message ${img.messageId} ("${img.name}"):` })
if (mat.ok) {
userContent.push({ type: 'input_image', image_url: mat.dataUrl, detail: 'auto' })
+ } else {
+ userContent.push({
+ type: 'input_text',
+ text: `The image "${img.name}" could not be loaded (${mat.reason}). Do not claim to have seen it.`,
+ })
}
}
+ for (const unavailable of collectedImages.unavailable) {
+ userContent.push({
+ type: 'input_text',
+ text: `The image "${unavailable.name}" attached to message ${unavailable.messageId} was not included because ${unavailable.reason}. Do not claim to have seen it.`,
+ })
+ }
const skippedImages = [
...faceMats.filter((x) => !x.mat.ok).map((x) => ({ url: x.f.url, kind: 'face' as const, reason: (x.mat as { reason: string }).reason })),
diff --git a/server/src/attachments/input-parts.ts b/server/src/attachments/input-parts.ts
new file mode 100644
index 0000000..c8e3899
--- /dev/null
+++ b/server/src/attachments/input-parts.ts
@@ -0,0 +1,63 @@
+import {
+ ATTACHMENT_TEXT_EXCERPT_BYTES,
+ normalizeAttachments,
+ type AttachmentDescriptor,
+} from '../../../shared/attachments.js'
+
+export type VisionCapability = 'supported' | 'unsupported' | 'unknown'
+
+export type AttachmentInputPart =
+ | { readonly type: 'text'; readonly text: string }
+ | { readonly type: 'image'; readonly imageUrl: string; readonly detail: 'auto' }
+ | { readonly type: 'unreadable-image'; readonly text: string }
+
+export interface AttachmentPartOptions {
+ readonly vision: VisionCapability
+ readonly messageId: string
+}
+
+function isImage(attachment: AttachmentDescriptor): boolean {
+ return attachment.kind === 'img' || attachment.mime?.startsWith('image/') === true
+}
+
+function imageNotice(name: string, capability: VisionCapability): string {
+ const reason = capability === 'unsupported'
+ ? 'the active model does not support image input'
+ : capability === 'unknown'
+ ? 'image support is unknown for the active model'
+ : 'the image data is unavailable'
+ return `Image "${name}" was not included: ${reason}. Its metadata is still available; do not claim to have seen it.`
+}
+
+/** Turn canonical descriptors into provider-neutral content parts. The caller
+ * owns secure materialization and supplies the ready `imageUrl`; keeping fetch
+ * policy out of this function makes the tri-state behavior testable. */
+export function attachmentInputParts(
+ attachments: unknown,
+ options: AttachmentPartOptions,
+): readonly AttachmentInputPart[] {
+ const parts: AttachmentInputPart[] = []
+ for (const attachment of normalizeAttachments(attachments)) {
+ if (!isImage(attachment)) continue
+ parts.push({ type: 'text', text: `Image attached to message ${options.messageId} ("${attachment.name}"):` })
+ if (options.vision === 'supported' && attachment.url) {
+ parts.push({ type: 'image', imageUrl: attachment.url, detail: 'auto' })
+ } else {
+ parts.push({ type: 'unreadable-image', text: imageNotice(attachment.name, options.vision) })
+ }
+ }
+ return parts
+}
+
+/** Build an excerpt part without performing I/O. `bytes` must be the exact
+ * bytes that will be shown; invalid UTF-8 is replaced rather than throwing. */
+export function textExcerptPart(
+ attachment: AttachmentDescriptor,
+ bytes: Uint8Array,
+): AttachmentInputPart {
+ const text = new TextDecoder().decode(bytes.subarray(0, ATTACHMENT_TEXT_EXCERPT_BYTES))
+ return {
+ type: 'text',
+ text: `File excerpt ("${attachment.name}"):\n${text}`,
+ }
+}
diff --git a/server/src/cli-bin.ts b/server/src/cli-bin.ts
index 9c6b341..3c7ab7e 100644
--- a/server/src/cli-bin.ts
+++ b/server/src/cli-bin.ts
@@ -18,7 +18,8 @@ async function main() {
await runComputerDaemon(argv.slice(2))
} catch (err) {
process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`)
- process.exitCode = 2
+ const pairing = argv.slice(2).some((arg) => arg === '--pair' || arg.startsWith('--pair='))
+ process.exitCode = pairing ? 1 : 2
}
return
}