{"record":{"id":"d3369b0b2eabc134","repo":"paperclipai/paperclip","slug":"provider-initialize-protocol-error","errorCode":"provider_initialize_protocol_error","errorMessage":"provider_initialize_protocol_error: provider=${provider} stage=${stage} missing durable provider session identity","messagePattern":"provider_initialize_protocol_error: provider=(.+?) stage=(.+?) missing durable provider session identity","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/backends/harness-driver-backend.ts","lineNumber":384,"sourceCode":"    }\n    if (bytes > maxBytes) return maxBytes + 1;\n  }\n  return bytes;\n}\n\nfunction assertProviderSessionIdentity(\n  session: HarnessSession,\n  provider: string,\n  stage: \"session.open\" | \"session.recover\",\n): void {\n  const ids = session.ids();\n  if (\n    typeof ids.driverSessionId !== \"string\" ||\n    ids.driverSessionId.trim().length === 0 ||\n    typeof ids.providerSessionId !== \"string\" ||\n    ids.providerSessionId.trim().length === 0\n  ) {\n    throw new Error(\n      `provider_initialize_protocol_error: provider=${provider} stage=${stage} missing durable provider session identity`,\n    );\n  }\n}\n\nclass HarnessNativeSession implements NativeSession {\n  #input: OpenNativeSessionInput;\n  readonly #session: HarnessSession;\n  #terminal: PrpTerminalState | null = null;\n  #explicitlyCancelled = false;\n  #protocolIntegrityFailure: NativeSessionProtocolIntegrityError | null = null;\n\n  #assertProtocolIntegrity(): void {\n    if (this.#protocolIntegrityFailure !== null)\n      throw this.#protocolIntegrityFailure;\n  }\n\n  #rethrowProtocolIntegrity(error: unknown): void {","sourceCodeStart":366,"sourceCodeEnd":402,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/backends/harness-driver-backend.ts#L366-L402","documentation":"assertProviderSessionIdentity enforces that after a provider initialize stage the driver returned a durable identity pair: a non-empty driverSessionId and a non-empty providerSessionId. These IDs are persisted to enable session recovery across process restarts. If either is missing or blank, the protocol contract was violated and the session open/recover fails with a coded protocol error.","triggerScenarios":"openSession or recoverSession completes a provider initialize/recover stage, but the driver's ids object has a missing, empty, or whitespace-only driverSessionId or providerSessionId.","commonSituations":"A driver implementation (or updated driver version) returning only a local session id without the provider's session id; a provider API change that stopped echoing a session identifier; a truncated or malformed initialize response parsed into ids with empty fields.","solutions":["Inspect the driver's initialize/recover response to see which of driverSessionId/providerSessionId is missing and fix the driver to return both.","Check for a driver/provider version mismatch and pin or upgrade the driver to one that returns durable session identity.","If the provider API changed its response shape, update the driver's response parsing to extract the new session id field."],"exampleFix":"// before (driver returns incomplete ids)\nreturn { ids: { driverSessionId: localId } };\n// after\nreturn { ids: { driverSessionId: localId, providerSessionId: response.providerSessionId } };","handlingStrategy":"try-catch","validationCode":"function hasDurableIdentity(ids) {\n  return typeof ids.driverSessionId === \"string\" && ids.driverSessionId.trim().length > 0 &&\n         typeof ids.providerSessionId === \"string\" && ids.providerSessionId.trim().length > 0;\n}","typeGuard":"function hasDurableIdentity(ids) {\n  return typeof ids?.driverSessionId === \"string\" && ids.driverSessionId.trim() !== \"\" &&\n         typeof ids?.providerSessionId === \"string\" && ids.providerSessionId.trim() !== \"\";\n}","tryCatchPattern":"try {\n  const session = await backend.openSession(input);\n} catch (err) {\n  if (err.message.includes(\"provider_initialize_protocol_error\") && err.message.includes(\"missing durable provider session identity\")) {\n    console.error(\"Driver did not return durable session ids; check driver version/response parsing\");\n  }\n  throw err;\n}","preventionTips":["Add a driver conformance test asserting both session ids are returned after initialize.","Pin driver versions and review response parsing when upgrading providers."],"tags":["protocol","session-identity","invariant"],"backgroundTag":"internal-invariant-violation","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}