vercel/ai · error · HarnessCapabilityUnsupportedError

ACP v1 does not define manual session compaction.

Error message

ACP v1 does not define manual session compaction.

What it means

The ACP v1 harness implements doCompact as an unconditional 'unsupported' throw because the ACP protocol version 1 defines no manual session-compaction operation. Any call to compact the session will always fail; compaction is not a capability of this transport.

Source

Thrown at packages/harness-acp/src/v1/acp-v1-harness.ts:1581

                  instructionMapping,
                  ...(options.instructions == null
                    ? {}
                    : { instructions: options.instructions }),
                }),
            ...(mcpServers == null ? {} : { mcpServers }),
            tools: turnStartConfig.tools,
            turnStartConfig,
            recoveryMode: {
              type: 'lossy-rerun',
              acpSessionId: latestACPSessionId!,
              reason: recoveryStatus?.reason ?? 'bridge process loss',
            },
          });
        },
      });
    },
    doCompact: async () => {
      throw unsupported({
        harnessId,
        message: 'ACP v1 does not define manual session compaction.',
      });
    },
    doSuspendTurn: async () => {
      if (stopped) {
        throw new Error(
          `${harnessId} ACP session ${sessionId} is stopped; cannot suspend.`,
        );
      }
      if (!turnInFlight) {
        throw new Error(
          `${harnessId} ACP session ${sessionId} has no in-flight turn to suspend.`,
        );
      }
      stopped = true;
      const lastSeenEventId = await channel.suspend();
      return {

View on GitHub (pinned to 69428b1f8b)

Solutions

Do not call compaction on ACP v1 sessions; gate the call on a capability check or harness type.
Start a new session instead of compacting when context grows too large.
Wait for/upgrade to an ACP protocol version that defines compaction, if one becomes available.

Example fix

// before
await session.compact();
// after
if (supportsCompaction(harnessId)) {
  await session.compact();
} else {
  session = await recreateSession();
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (harnessId.startsWith('acp') || isACPHarness(session)) {
  throw new Error('Manual compaction is not supported on ACP v1 sessions');
}

Type guard

function supportsCompaction(session: { harnessId?: string }): boolean {
  return !(session.harnessId ?? '').toLowerCase().includes('acp');
}

Try / catch

try {
  await session.compact();
} catch (e) {
  if (String(e?.message).includes('manual session compaction')) {
    session = await recreateSession(); // restart instead of compacting
  } else throw e;
}

Prevention

Gate compaction behind a capability query on the session
Never call compaction unconditionally in harness-agnostic loops
Plan context management (new session) for ACP-backed long runs

When it happens

Trigger: Explicitly invoking the session's doCompact / compact API on a session created via createACPV1.

Common situations: Writing harness-agnostic code that unconditionally calls compaction on every session; long-running agent sessions approaching context limits where an ACP backend is in use.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/5a4c46155df3bd96. Report an issue: GitHub.