vercel/ai · error · HarnessBridgeCapabilityUnsupportedError

Cold ACP session restoration requires the agent to advertise

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.

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)

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 sessi
• ACP session initialization did not produce a session.
• ACP authentication and session profile settings cannot chang
• Recovered ACP session is disposed.
• The ACP implementation did not load the active harness-owned

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