vercel/ai · error · HarnessBridgeCapabilityUnsupportedError

ACP process-loss rerun requires the agent to advertise sessi

Error message

ACP process-loss rerun requires the agent to advertise sessionCapabilities.resume; a fresh unrelated ACP session will not be created.

What it means

assertACPResumeCapability checks that the agent's initialization response advertises agentCapabilities.sessionCapabilities.resume. Rerunning after a process loss requires resuming the same ACP session; if the agent cannot resume, the library throws a HarnessBridgeCapabilityUnsupportedError instead of silently creating a fresh, unrelated session (which would lose context).

Source

Thrown at packages/harness-acp/src/v1/bridge/recovered-session.ts:30

  }): Promise<acp.PromptResponse>;
  nextUpdate(): Promise<acp.ActiveSessionMessage>;
  dispose(): void;
};

export function assertACPResumeCapability({
  initialization,
  harnessId,
}: {
  initialization: ACPInitializeResult;
  harnessId: string;
}): void {
  const sessionCapabilities = initialization.agentCapabilities
    ?.sessionCapabilities as Readonly<Record<string, unknown>> | undefined;
  if (
    sessionCapabilities?.resume == null ||
    sessionCapabilities.resume === false
  ) {
    throw new HarnessBridgeCapabilityUnsupportedError({
      harnessId,
      message:
        'ACP process-loss rerun requires the agent to advertise sessionCapabilities.resume; a fresh unrelated ACP session will not be created.',
    });
  }
}

export function createACPRecoveredSession({
  agent,
  sessionId,
  restorationResponse,
  updates,
}: {
  agent: acp.ClientContext;
  sessionId: string;
  restorationResponse: acp.ResumeSessionResponse | acp.LoadSessionResponse;
  updates: ReturnType<typeof createACPRecoveredSessionUpdates>;
}): ACPActiveSession {

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Upgrade the ACP agent to a version that advertises sessionCapabilities.resume.
2. Update the agent's initialization response to include agentCapabilities.sessionCapabilities.resume: true if it does support resuming.
3. Use a harness/run mode that tolerates fresh sessions if resume cannot be supported.
4. Verify the correct agent binary/implementation is being launched (an older one may be on PATH).

Example fix

// agent initialize result (before)
{ agentCapabilities: {} }
// after
{ agentCapabilities: { sessionCapabilities: { resume: true } } }

const caps = initialization.agentCapabilities?.sessionCapabilities as Record<string, unknown> | undefined;
if (caps?.resume == null || caps.resume === false) {
  console.warn('Agent cannot resume sessions; process-loss rerun will fail.');
}

function supportsResume(initialization: ACPInitializeResult): boolean {
  const caps = initialization.agentCapabilities?.sessionCapabilities as
    | Readonly<Record<string, unknown>>
    | undefined;
  return caps?.resume != null && caps.resume !== false;
}

import { HarnessBridgeCapabilityUnsupportedError } from '...';
try {
  await ensureSession();
} catch (error) {
  if (HarnessBridgeCapabilityUnsupportedError.isInstance?.(error) || (error as Error).message.includes('sessionCapabilities.resume')) {
    // fall back to a fresh-session workflow
    return;
  }
  throw error;
}

When it happens

Trigger: Attempting a process-loss rerun (ensureSession) against an agent whose initialization lacks sessionCapabilities.resume or advertises resume: false.

Common situations: Older agent versions that do not implement resume; agent implementations that only support fresh sessions; a capability negotiation where the agent omits sessionCapabilities entirely.

Related errors

• Cold ACP session restoration requires the agent to advertise
• The persisted ACP turn start configuration is incompatible w
• ACP session initialization did not produce a session.
• ACP authentication and session profile settings cannot chang
• Recovered ACP session is disposed.

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