{"record":{"id":"d5d21333878ffdfa","repo":"paperclipai/paperclip","slug":"provider-initialize-protocol-error-d5d213","errorCode":"provider_initialize_protocol_error","errorMessage":"provider_initialize_protocol_error: provider=${this.#options.driverIdentity?.kind ?? \"codex\"} stage=session.open omitted provider session identity","messagePattern":"provider_initialize_protocol_error: provider=(.+?) stage=session\\.open omitted provider session identity","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.ts","lineNumber":794,"sourceCode":"    }\n  }\n\n  #openedThread(\n    response: Record<string, unknown>,\n    initialize: Record<string, unknown>,\n    workingDirectory: string,\n    collaborationMode: Record<string, unknown> | null,\n  ): OpenedCodexThread {\n    const thread = record(response.thread);\n    const threadId = text(thread.id);\n    if (threadId.length === 0)\n      throw new Error(\"Codex thread response omitted thread.id\");\n    const providerSessionId = text(thread.sessionId) || null;\n    if (\n      this.#options.requireProviderSessionIdentity &&\n      providerSessionId === null\n    ) {\n      throw new Error(\n        `provider_initialize_protocol_error: provider=${this.#options.driverIdentity?.kind ?? \"codex\"} stage=session.open omitted provider session identity`,\n      );\n    }\n    const activePermissionProfile = record(thread.activePermissionProfile);\n    const permissionProfileId = text(activePermissionProfile.id);\n    const requestedMode = this.#options.requestedCollaborationMode ?? \"default\";\n    const requiredPermissionProfile =\n      text(createSecuredCodexThreadParams(workingDirectory, requestedMode, true, false, this.#options.environment).permissions);\n    if (\n      permissionProfileId.length > 0 &&\n      permissionProfileId !== requiredPermissionProfile\n    ) {\n      throw new Error(\n        \"Codex thread did not activate the required filesystem permission profile\",\n      );\n    }\n    const configuredPermissionProfile = {\n      ...activePermissionProfile,","sourceCodeStart":776,"sourceCodeEnd":812,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/codex/codex-app-server-driver-impl.ts#L776-L812","documentation":"This is the driver's strict session-identity gate: when `requireProviderSessionIdentity` is enabled, the Codex thread response must include a non-empty `sessionId`. Without it Paperclip cannot tie local run records to the provider-side session for resumption and audit. The error is namespaced `provider_initialize_protocol_error` with the driver kind and stage embedded in the message.","triggerScenarios":"Starting a Codex session with `options.requireProviderSessionIdentity === true` while the provider's thread/new response contains `sessionId: null`, an empty string, or omits the field entirely.","commonSituations":"Upgrading Paperclip to a build that enforces provider session identity while running a Codex version that does not report `thread.sessionId`; self-hosted or proxied app-servers that strip the field; test doubles that only populate thread.id.","solutions":["Upgrade the Codex app-server to a version that returns thread.sessionId","Disable requireProviderSessionIdentity if provider identity is genuinely unavailable and resumption is not needed","Inspect the raw thread/new response to verify whether sessionId is present under a different name and adapt the mapping"],"exampleFix":"// before\nnew CodexAppServerDriver({ requireProviderSessionIdentity: true });\n// after (if provider cannot supply sessionId)\nnew CodexAppServerDriver({ requireProviderSessionIdentity: false });","handlingStrategy":"validation","validationCode":"const providerSessionId = typeof thread.sessionId === \"string\" ? thread.sessionId : \"\";\nconst identityRequired = options.requireProviderSessionIdentity ?? true;\nif (identityRequired && providerSessionId.length === 0) {\n  throw new Error(\"provider session identity unavailable; upgrade Codex or relax the requirement\");\n}","typeGuard":"function hasSessionId(t: unknown): t is { sessionId: string } {\n  return typeof t === \"object\" && t !== null && typeof (t as { sessionId?: unknown }).sessionId === \"string\" && (t as { sessionId: string }).sessionId.length > 0;\n}","tryCatchPattern":"try {\n  await driver.opened(...);\n} catch (err) {\n  if (String(err.message).includes(\"omitted provider session identity\")) {\n    // check Codex version, or set requireProviderSessionIdentity=false for this provider\n  }\n  throw err;\n}","preventionTips":["Verify thread.sessionId is present in the provider's thread/new payload before enabling strict identity","Keep the Codex app-server at a version known to report sessionId","Use an integration smoke test that opens a session and asserts identity fields"],"tags":["codex","protocol","session-identity"],"backgroundTag":"missing-required-argument","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"}