1/**

2 * Image offload executor for the compaction seam. When an image-capable route

3 * fails a request with `IMAGE_OFFLOAD_REQUIRED`, the plugin records one

4 * `image/offload` decision selecting the oldest retained input occurrences

5 * and retries through the agent or compaction summary error waterfall. Every route

6 * sends placeholder text for those occurrences in subsequent requests.

7 *

8 * @module @deepseek-ai/dsh-compaction-image-offload

9 */

10

11import type { Context } from '@deepseek-ai/cordis'

12import type {} from '@deepseek-ai/dsh-compaction'

13import type { RequestErrorAction } from '@deepseek-ai/dsh-agent'

14import { IMAGE_OFFLOAD_REQUIRED_CODE, LlmError } from '@deepseek-ai/dsh-llm'

15import { offloadOldestImages } from './image-offload.ts'

16import { imageOffloadProjection } from './projection.ts'

17

18export const name = 'compaction-image-offload'

19export const inject = ['agents', 'sessions']

20

21/**

22 * Mount agent and summary recovery listeners without configuration.

23 * @param ctx - the plugin context.

24 */

25export function apply(ctx: Context): void {

26 ctx.sessions.registerMessageProjection(imageOffloadProjection)

27 ctx.on('agent/request-error', ({ agent, failure }, next): Promise<RequestErrorAction> => {

28 if (failure.code !== IMAGE_OFFLOAD_REQUIRED_CODE || failure.offloadImages === undefined) return next()

29 // A durable surface repair, not a provider retry: it spends no retry budget and logs no retry event.

30 if (!offloadOldestImages(agent.session, agent.session.surface.nodes, failure.offloadImages)) return next()

31 return Promise.resolve<RequestErrorAction>({ kind: 'retry' })

32 })

33 ctx.on('compaction/summary-error', ({ session, sourceEventSeqs, error, signal }, next) => {

34 if (!(error instanceof LlmError)

35 || error.code !== IMAGE_OFFLOAD_REQUIRED_CODE

36 || error.failure.offloadImages === undefined) return next()

37 signal?.throwIfAborted()

38 if (!offloadOldestImages(session, sourceEventSeqs, error.failure.offloadImages)) return next()

39 return true

40 })

41}