fix(integrations): address Photon iMessage review findings

Restores type-check: `downloadServableFileFromStorage` made `maxBytes`
required upstream, and the merge at a3e3f43 left the Photon media helper
calling it with three arguments. Passing the 100MB ceiling also bounds the
upload read — the declared size is checked before any bytes move — closing
the upload-side twin of the download issue reviewers flagged.

Outbound deliveries no longer reach a trigger. Photon echoes our own sends
back on the same webhook tagged `outbound`, so a reply workflow could be
re-triggered by its own reply and loop. `shouldSkipEvent` drops them before
routing, testing for an explicit `outbound` rather than for `inbound` so a
delivery that omits the optional field keeps firing as it does today.

Eviction can no longer close a connection mid-operation. The hand-rolled Map
LRU becomes an `LRUCache` (per .claude/rules/sim-caching.md) whose entries
carry a lease count: eviction only marks an entry, and `stop()` runs when the
last in-flight operation releases it. All 20 operations run through
`withPhotonContext`, which holds the lease in a `finally`. The entry is
published before the first await, so concurrent callers for one project share
a single construction instead of racing two connections.

Also: `getPhotonMessage` surfaces native voice memos as attachments (with
`size`), matching the webhook's `collectAttachments`, so Download Attachment
can be driven from its output; oversized attachments are rejected on their
declared size before any bytes are fetched, with the post-read check kept as a
backstop; only an `UnsupportedError` maps to the dedicated-line message, so
auth, network, and invalid-handle failures keep their own cause; the webhook
fixtures drop 11 `as any` casts for the real handler context types; and the
local `isRecord` gives way to `isRecordLike` from `@sim/utils/object`.

Adds 11 tests: pooling reuse, the lease-vs-eviction race, failed-construction
eviction, voice attachments through reply/group wrappers, both size-limit
paths, both group-create error paths, and the direction filter.

Author: qwerzl

apps/docs/content/docs/en/integrations/photon_imessage.mdx

@@ -401,7 +401,7 @@ Fetch a single message with its text, sender, and attachment metadata
 | `contentType` | string | Content kind \(text, attachment, reaction, and so on\) |
 | `senderId` | string | Sender handle |
 | `timestamp` | string | ISO 8601 send time |
-| `attachments` | json | Attachment metadata as an array of \{ id, name, mimeType \} |
+| `attachments` | json | Attachment metadata as an array of \{ id, name, mimeType, size \}, covering media and voice memos |
 
 ### Download Attachment
 
@@ -475,7 +475,7 @@ A **Trigger** is a block that starts a workflow when an event happens in this se
 
 ### Photon Any Event
 
-Trigger workflow on every Photon delivery: messages, tapbacks, and read receipts
+Trigger workflow on every inbound Photon delivery: messages, tapbacks, and read receipts
 
 #### Configuration
 

apps/sim/app/api/tools/photon_imessage/route-helpers.ts

@@ -1,6 +1,7 @@
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import { NextResponse } from 'next/server'
+import { isPayloadSizeLimitError } from '@/lib/core/utils/stream-limits'
 import { processFilesToUserFiles, type RawFileInput } from '@/lib/uploads/utils/file-utils'
 import { downloadServableFileFromStorage } from '@/lib/uploads/utils/file-utils.server'
 import { docNotReadyResponse } from '@/lib/uploads/utils/servable-file-response'
@@ -16,6 +17,16 @@ export interface PhotonRouteContext {
 /** Attachments ride the gRPC stream; cap uploads the same way Linq caps its pre-upload. */
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024
 
+function fileTooLargeError(sizeBytes: number): NextResponse {
+  return NextResponse.json(
+    {
+      success: false,
+      error: `File exceeds the 100MB attachment limit (${(sizeBytes / (1024 * 1024)).toFixed(2)}MB)`,
+    },
+    { status: 400 }
+  )
+}
+
 export interface MaterializedFile {
   buffer: Buffer
   fileName: string
@@ -59,14 +70,19 @@ export async function materializePhotonFile(
     const denied = await assertToolFileAccess(userFile.key, ctx.userId, ctx.requestId, logger)
     if (denied) return denied
     try {
-      const resolved = await downloadServableFileFromStorage(userFile, ctx.requestId, logger)
+      const resolved = await downloadServableFileFromStorage(userFile, ctx.requestId, logger, {
+        maxBytes: MAX_UPLOAD_BYTES,
+      })
       buffer = resolved.buffer
       if (!resolvedContentType) {
         resolvedContentType = resolved.contentType || userFile.type || 'application/octet-stream'
       }
     } catch (error) {
       const notReady = docNotReadyResponse(error)
       if (notReady) return notReady
+      if (isPayloadSizeLimitError(error)) {
+        return fileTooLargeError(error.observedBytes ?? userFile.size)
+      }
       logger.error(`[${ctx.requestId}] Failed to download Photon media file:`, error)
       return NextResponse.json(
         { success: false, error: getErrorMessage(error, 'Unknown error occurred') },
@@ -86,13 +102,7 @@ export async function materializePhotonFile(
     return NextResponse.json({ success: false, error: 'File is empty' }, { status: 400 })
   }
   if (buffer.length > MAX_UPLOAD_BYTES) {
-    return NextResponse.json(
-      {
-        success: false,
-        error: `File exceeds the 100MB attachment limit (${(buffer.length / (1024 * 1024)).toFixed(2)}MB)`,
-      },
-      { status: 400 }
-    )
+    return fileTooLargeError(buffer.length)
   }
 
   return { buffer, fileName: resolvedFilename, mimeType: resolvedContentType }

apps/sim/app/api/tools/photon_imessage/utils.test.ts

@@ -0,0 +1,282 @@
+/**
+ * @vitest-environment node
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+/**
+ * The real SDK opens gRPC connections on construction, so both Spectrum packages are mocked. The
+ * mocks are deliberately thin: these tests cover the pooling, attachment, and error-mapping logic
+ * this module owns, not the provider's behavior.
+ */
+const {
+  MockUnsupportedError,
+  contentBuilder,
+  mockGetAttachment,
+  mockGetMessage,
+  mockSpaceCreate,
+  mockSpaceGet,
+  mockSpectrum,
+  mockStop,
+} = vi.hoisted(() => ({
+  MockUnsupportedError: class MockUnsupportedError extends Error {},
+  contentBuilder: (type: string) => vi.fn((...args: unknown[]) => ({ type, args })),
+  mockGetAttachment: vi.fn(),
+  mockGetMessage: vi.fn(),
+  mockSpaceCreate: vi.fn(),
+  mockSpaceGet: vi.fn(),
+  mockSpectrum: vi.fn(),
+  mockStop: vi.fn(),
+}))
+
+vi.mock('@spectrum-ts/core', () => ({
+  Spectrum: mockSpectrum,
+  UnsupportedError: MockUnsupportedError,
+  addMember: contentBuilder('addMember'),
+  attachment: contentBuilder('attachment'),
+  avatar: contentBuilder('avatar'),
+  edit: contentBuilder('edit'),
+  leaveSpace: contentBuilder('leaveSpace'),
+  poll: contentBuilder('poll'),
+  reaction: contentBuilder('reaction'),
+  read: contentBuilder('read'),
+  removeMember: contentBuilder('removeMember'),
+  rename: contentBuilder('rename'),
+  reply: contentBuilder('reply'),
+  text: contentBuilder('text'),
+  typing: contentBuilder('typing'),
+  unsend: contentBuilder('unsend'),
+  voice: contentBuilder('voice'),
+}))
+
+vi.mock('@spectrum-ts/imessage', () => ({
+  effect: contentBuilder('effect'),
+  imessage: Object.assign(
+    vi.fn(() => ({
+      space: { get: mockSpaceGet, create: mockSpaceCreate },
+      user: vi.fn(async (handle: string) => ({ id: handle })),
+      getAttachment: mockGetAttachment,
+      shareContactCard: vi.fn(),
+      background: vi.fn(),
+    })),
+    {
+      config: vi.fn(() => ({ platform: 'imessage' })),
+      effect: { message: { balloons: 'com.apple.messages.effect.CKBalloonEffect' } },
+    }
+  ),
+}))
+
+import {
+  createPhotonGroup,
+  downloadPhotonAttachment,
+  getPhotonMessage,
+} from '@/app/api/tools/photon_imessage/utils'
+
+const CREDS = { projectId: 'proj-1', projectSecret: 'secret-1' }
+
+/** A chat GUID addresses an existing space directly, so no DM is created along the way. */
+const CHAT_ID = 'any;-;+14155551234'
+
+/** Mirrors the pool ceiling in the module under test. */
+const MAX_CACHED_INSTANCES = 8
+
+/** Point `space.get` at a space whose single message carries {@link content}. */
+function stubMessage(content: unknown) {
+  mockSpectrum.mockResolvedValue({ stop: mockStop })
+  mockGetMessage.mockResolvedValue({
+    id: 'msg-1',
+    content,
+    sender: { id: '+14155551234' },
+    timestamp: new Date('2026-08-21T10:00:00.000Z'),
+  })
+  mockSpaceGet.mockResolvedValue({ id: CHAT_ID, getMessage: mockGetMessage, send: vi.fn() })
+}
+
+describe('photon iMessage tool client', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockStop.mockResolvedValue(undefined)
+  })
+
+  describe('instance pooling', () => {
+    it('reuses one instance across calls for the same project', async () => {
+      stubMessage({ type: 'text', text: 'hi' })
+
+      await getPhotonMessage({ ...CREDS, chatId: CHAT_ID, messageId: 'msg-1' })
+      await getPhotonMessage({ ...CREDS, chatId: CHAT_ID, messageId: 'msg-1' })
+
+      expect(mockSpectrum).toHaveBeenCalledTimes(1)
+    })
+
+    it('never stops an instance while an operation is still using it', async () => {
+      // Push the held project past the pool ceiling while its own download is still in flight, so
+      // `stop()` on that instance must wait for the download to finish.
+      let releaseDownload: (() => void) | undefined
+      mockGetAttachment.mockImplementationOnce(async () => {
+        await new Promise<void>((resolve) => {
+          releaseDownload = resolve
+        })
+        return {
+          name: 'a.jpg',
+          mimeType: 'image/jpeg',
+          size: 1,
+          read: async () => Buffer.from('x'),
+        }
+      })
+      stubMessage({ type: 'text', text: 'hi' })
+
+      // A dedicated spy for the held instance: evicting the other pooled projects legitimately
+      // stops those, and only this one must survive until its download completes.
+      const heldStop = vi.fn().mockResolvedValue(undefined)
+      mockSpectrum.mockResolvedValueOnce({ stop: heldStop })
+
+      const held = downloadPhotonAttachment({
+        projectId: 'held-project',
+        projectSecret: 's',
+        attachmentId: 'att-1',
+      })
+      // Let the held download reach its await before filling the pool behind it.
+      await vi.waitFor(() => expect(releaseDownload).toBeDefined())
+
+      for (let index = 0; index < MAX_CACHED_INSTANCES; index += 1) {
+        await getPhotonMessage({
+          projectId: `project-${index}`,
+          projectSecret: 's',
+          chatId: CHAT_ID,
+          messageId: 'msg-1',
+        })
+      }
+
+      expect(heldStop).not.toHaveBeenCalled()
+
+      releaseDownload?.()
+      await expect(held).resolves.toMatchObject({ attachmentId: 'att-1' })
+
+      await vi.waitFor(() => expect(heldStop).toHaveBeenCalledTimes(1))
+    })
+
+    it('does not cache a failed construction', async () => {
+      mockSpectrum.mockRejectedValueOnce(new Error('bad credentials'))
+
+      await expect(
+        getPhotonMessage({
+          projectId: 'transient',
+          projectSecret: 's',
+          chatId: CHAT_ID,
+          messageId: 'msg-1',
+        })
+      ).rejects.toThrow('bad credentials')
+
+      stubMessage({ type: 'text', text: 'hi' })
+      await expect(
+        getPhotonMessage({
+          projectId: 'transient',
+          projectSecret: 's',
+          chatId: CHAT_ID,
+          messageId: 'msg-1',
+        })
+      ).resolves.toMatchObject({ messageId: 'msg-1' })
+    })
+  })
+
+  describe('getPhotonMessage attachments', () => {
+    it('surfaces a native voice memo so Download Attachment can be driven from it', async () => {
+      stubMessage({
+        type: 'voice',
+        id: 'voice-1',
+        name: 'Audio Message.caf',
+        mimeType: 'audio/x-caf',
+        size: 2048,
+      })
+
+      const result = await getPhotonMessage({ ...CREDS, chatId: CHAT_ID, messageId: 'msg-1' })
+
+      expect(result.attachments).toEqual([
+        { id: 'voice-1', name: 'Audio Message.caf', mimeType: 'audio/x-caf', size: 2048 },
+      ])
+    })
+
+    it('walks reply and group wrappers the way the webhook handler does', async () => {
+      stubMessage({
+        type: 'reply',
+        content: {
+          type: 'group',
+          items: [
+            { content: { type: 'text', text: 'look' } },
+            {
+              content: {
+                type: 'attachment',
+                id: 'att-1',
+                name: 'a.jpg',
+                mimeType: 'image/jpeg',
+                size: 10,
+              },
+            },
+            { content: { type: 'voice', id: 'voice-1', mimeType: 'audio/x-caf' } },
+          ],
+        },
+      })
+
+      const result = await getPhotonMessage({ ...CREDS, chatId: CHAT_ID, messageId: 'msg-1' })
+
+      expect(result.attachments.map((attachment) => attachment.id)).toEqual(['att-1', 'voice-1'])
+      expect(result.attachments[1]).toEqual({
+        id: 'voice-1',
+        name: null,
+        mimeType: 'audio/x-caf',
+        size: null,
+      })
+    })
+  })
+
+  describe('downloadPhotonAttachment', () => {
+    it('rejects an oversized attachment on its declared size, before reading any bytes', async () => {
+      const read = vi.fn()
+      mockGetAttachment.mockResolvedValue({
+        name: 'huge.mov',
+        mimeType: 'video/quicktime',
+        size: 60 * 1024 * 1024,
+        read,
+      })
+      stubMessage({ type: 'text', text: 'hi' })
+
+      await expect(
+        downloadPhotonAttachment({ ...CREDS, attachmentId: 'att-huge' })
+      ).rejects.toThrow(/above the 50MB download limit/)
+      expect(read).not.toHaveBeenCalled()
+    })
+
+    it('re-checks the delivered bytes when the provider declares no size', async () => {
+      mockGetAttachment.mockResolvedValue({
+        name: 'huge.mov',
+        mimeType: 'video/quicktime',
+        size: undefined,
+        read: async () => Buffer.alloc(51 * 1024 * 1024),
+      })
+      stubMessage({ type: 'text', text: 'hi' })
+
+      await expect(
+        downloadPhotonAttachment({ ...CREDS, attachmentId: 'att-unknown' })
+      ).rejects.toThrow(/above the 50MB download limit/)
+    })
+  })
+
+  describe('createPhotonGroup', () => {
+    it('explains the dedicated-line requirement when the provider says unsupported', async () => {
+      stubMessage({ type: 'text', text: 'hi' })
+      mockSpaceCreate.mockRejectedValue(new MockUnsupportedError('group create is remote-only'))
+
+      await expect(
+        createPhotonGroup({ ...CREDS, handles: ['+15551112222', '+15553334444'] })
+      ).rejects.toThrow(/requires a dedicated Photon line/)
+    })
+
+    it('leaves every other failure with its own cause', async () => {
+      stubMessage({ type: 'text', text: 'hi' })
+      mockSpaceCreate.mockRejectedValue(new Error('Unauthorized: invalid project secret'))
+
+      await expect(
+        createPhotonGroup({ ...CREDS, handles: ['+15551112222', '+15553334444'] })
+      ).rejects.toThrow('Unauthorized: invalid project secret')
+    })
+  })
+})