vercel/ai · error · HarnessBridgeCapabilityUnsupportedError

Cold ACP session restoration requires the agent to…

Error message

Cold ACP session restoration requires the agent to advertise sessionCapabilities.resume or loadSession; a fresh unrelated ACP session will not be created.

What it means

resolveACPSessionRestorationMethod determines how a cold (new process) ACP session can be restored: 'resume' if sessionCapabilities.resume is advertised, else 'load' if loadSession is true. If neither capability is advertised, it throws HarnessBridgeCapabilityUnsupportedError because restoring the session is impossible without creating an unrelated fresh session.

Solutions

1. Upgrade the agent so it advertises sessionCapabilities.resume (or loadSession).
2. Set loadSession: true in the agent's agentCapabilities if it implements load.
3. Use a non-restoring run mode if the agent cannot support session restoration.
4. Verify you are connecting to the intended agent build (capabilities differ across versions).

Example fix

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

const caps = initialization.agentCapabilities;
const resume = (caps?.sessionCapabilities as Record<string, unknown> | undefined)?.resume;
if (resume == null || resume === false) {
  if (caps?.loadSession !== true) {
    console.warn('Agent supports neither resume nor loadSession; cold restoration will fail.');
  }
}

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

import { HarnessBridgeCapabilityUnsupportedError } from '...';
try {
  const method = resolveACPSessionRestorationMethod({ initialization, harnessId });
} catch (error) {
  if (HarnessBridgeCapabilityUnsupportedError.isInstance?.(error)) {
    // start a fresh session instead of restoring
  }
  throw error;
}

When it happens

Trigger: Cold-starting/restoring an ACP session against an agent whose initialize response lacks both agentCapabilities.sessionCapabilities.resume and agentCapabilities.loadSession === true.

Common situations: Older agent versions predating both capabilities; agents that only support fresh sessions; capability fields omitted due to an agent bug or mismatched protocol version.

Related errors

• ACP process-loss rerun requires the agent to advertise…
• ACP authentication and session profile settings cannot…
• ACP session initialization did not produce a session.
• Recovered ACP session is disposed.
• The ACP implementation did not load the active…

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

Appendix: source

Thrown at packages/harness-acp/src/v1/bridge/session-lifecycle.ts:25

export function resolveACPSessionRestorationMethod({
  initialization,
  harnessId,
}: {
  initialization: ACPInitializeResult;
  harnessId: string;
}): ACPSessionRestorationMethod {
  const sessionCapabilities = initialization.agentCapabilities
    ?.sessionCapabilities as Readonly<Record<string, unknown>> | undefined;
  if (
    sessionCapabilities?.resume != null &&
    sessionCapabilities.resume !== false
  ) {
    return 'resume';
  }
  if (initialization.agentCapabilities?.loadSession === true) {
    return 'load';
  }
  throw new HarnessBridgeCapabilityUnsupportedError({
    harnessId,
    message:
      'Cold ACP session restoration requires the agent to advertise sessionCapabilities.resume or loadSession; a fresh unrelated ACP session will not be created.',
  });
}

export async function restoreACPBridgeSession({
  agent,
  initialization,
  sessionId,
  cwd,
  mcpServers,
  meta,
  harnessId,
  setHistoricalUpdatesSuppressed,
  discardCapturedHistory,
}: {
  agent: acp.ClientContext;

View on GitHub (pinned to 69428b1f8b)