{"record":{"id":"99c4a18db81f1119","repo":"vercel/ai","slug":"cold-acp-session-restoration-requires-the-agent-to","errorCode":null,"errorMessage":"Cold ACP session restoration requires the agent to advertise sessionCapabilities.resume or loadSession; a fresh unrelated ACP session will not be created.","messagePattern":"Cold ACP session restoration requires the agent to advertise sessionCapabilities\\.resume or loadSession; a fresh unrelated ACP session will not be created\\.","errorType":"exception","errorClass":"HarnessBridgeCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/bridge/session-lifecycle.ts","lineNumber":25,"sourceCode":"export function resolveACPSessionRestorationMethod({\n  initialization,\n  harnessId,\n}: {\n  initialization: ACPInitializeResult;\n  harnessId: string;\n}): ACPSessionRestorationMethod {\n  const sessionCapabilities = initialization.agentCapabilities\n    ?.sessionCapabilities as Readonly<Record<string, unknown>> | undefined;\n  if (\n    sessionCapabilities?.resume != null &&\n    sessionCapabilities.resume !== false\n  ) {\n    return 'resume';\n  }\n  if (initialization.agentCapabilities?.loadSession === true) {\n    return 'load';\n  }\n  throw new HarnessBridgeCapabilityUnsupportedError({\n    harnessId,\n    message:\n      'Cold ACP session restoration requires the agent to advertise sessionCapabilities.resume or loadSession; a fresh unrelated ACP session will not be created.',\n  });\n}\n\nexport async function restoreACPBridgeSession({\n  agent,\n  initialization,\n  sessionId,\n  cwd,\n  mcpServers,\n  meta,\n  harnessId,\n  setHistoricalUpdatesSuppressed,\n  discardCapturedHistory,\n}: {\n  agent: acp.ClientContext;","sourceCodeStart":7,"sourceCodeEnd":43,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/bridge/session-lifecycle.ts#L7-L43","documentation":"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.","triggerScenarios":"Cold-starting/restoring an ACP session against an agent whose initialize response lacks both agentCapabilities.sessionCapabilities.resume and agentCapabilities.loadSession === true.","commonSituations":"Older agent versions predating both capabilities; agents that only support fresh sessions; capability fields omitted due to an agent bug or mismatched protocol version.","solutions":["Upgrade the agent so it advertises sessionCapabilities.resume (or loadSession).","Set loadSession: true in the agent's agentCapabilities if it implements load.","Use a non-restoring run mode if the agent cannot support session restoration.","Verify you are connecting to the intended agent build (capabilities differ across versions)."],"exampleFix":"// agent initialize result (before)\n{ agentCapabilities: { experimental: {} } }\n// after\n{ agentCapabilities: { sessionCapabilities: { resume: true }, loadSession: true } }","handlingStrategy":"validation","validationCode":"const caps = initialization.agentCapabilities;\nconst resume = (caps?.sessionCapabilities as Record<string, unknown> | undefined)?.resume;\nif (resume == null || resume === false) {\n  if (caps?.loadSession !== true) {\n    console.warn('Agent supports neither resume nor loadSession; cold restoration will fail.');\n  }\n}","typeGuard":"function supportsColdRestore(initialization: ACPInitializeResult): boolean {\n  const caps = initialization.agentCapabilities;\n  const resume = (caps?.sessionCapabilities as Readonly<Record<string, unknown>> | undefined)?.resume;\n  return (resume != null && resume !== false) || caps?.loadSession === true;\n}","tryCatchPattern":"import { HarnessBridgeCapabilityUnsupportedError } from '...';\ntry {\n  const method = resolveACPSessionRestorationMethod({ initialization, harnessId });\n} catch (error) {\n  if (HarnessBridgeCapabilityUnsupportedError.isInstance?.(error)) {\n    // start a fresh session instead of restoring\n  }\n  throw error;\n}","preventionTips":["Probe agent capabilities after initialize and branch behavior accordingly.","Upgrade agents that lack both resume and loadSession if restoration is required.","Pin agent versions in deployment to keep capability sets stable."],"tags":["acp","capability","session","restore"],"backgroundTag":"unsupported-capability","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}