{"record":{"id":"f8e25ee6ef4a5a36","repo":"vercel/ai","slug":"harness-cline-cannot-require-structured-output-w","errorCode":null,"errorMessage":"Harness 'cline' cannot require structured output with the openai-codex-cli provider because that provider does not expose external tools.","messagePattern":"Harness 'cline' cannot require structured output with the openai-codex-cli provider because that provider does not expose external tools\\.","errorType":"exception","errorClass":"HarnessCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-cline/src/cline-session.ts","lineNumber":596,"sourceCode":"    const userTools = turnOpts.tools;\n    const skillsRuntime = createClineSkillsRuntime({\n      skills: turnOpts.skills,\n    });\n    if (\n      turnOpts.responseFormat?.type === 'json' &&\n      turnOpts.responseFormat.schema == null\n    ) {\n      throw new HarnessCapabilityUnsupportedError({\n        message:\n          \"Harness 'cline' requires a JSON schema for structured output.\",\n        harnessId: HARNESS_ID,\n      });\n    }\n    if (\n      turnOpts.responseFormat?.type === 'json' &&\n      agentModel.providerId === 'openai-codex-cli'\n    ) {\n      throw new HarnessCapabilityUnsupportedError({\n        message:\n          \"Harness 'cline' cannot require structured output with the openai-codex-cli provider because that provider does not expose external tools.\",\n        harnessId: HARNESS_ID,\n      });\n    }\n\n    if (turnOpts.model != null && turnOpts.model !== activeModelId) {\n      activeModelId = turnOpts.model;\n      agentModel = createClineAgentModel({\n        settings: input.settings,\n        clientApp: input.clientApp,\n        modelId: activeModelId,\n      });\n    }\n\n    const signature = JSON.stringify({\n      modelId: activeModelId,\n      tools: userTools,","sourceCodeStart":578,"sourceCodeEnd":614,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-cline/src/cline-session.ts#L578-L614","documentation":"Cline implements required structured output through its tool mechanism, but the openai-codex-cli provider does not expose external tools to the harness. Combining responseFormat.type === 'json' with a model whose providerId is 'openai-codex-cli' therefore cannot be honored, and a HarnessCapabilityUnsupportedError is thrown. This is a hard provider capability limitation, not a configuration typo.","triggerScenarios":"Running a Cline session with agentModel.providerId === 'openai-codex-cli' and calling prompt with responseFormat: { type: 'json', schema: ... } that requires structured output enforcement.","commonSituations":"Switching a structured-output workflow from a tool-capable provider (e.g. anthropic, openai) to the codex CLI provider without removing or relaxing responseFormat; building provider-agnostic code that always sets responseFormat regardless of model.","solutions":["Use a provider that exposes external tools when you need required JSON output (or run the same workflow against a different agentModel).","Remove the required responseFormat for codex-cli runs and instead instruct the model to emit JSON in the prompt, then parse and validate with safeParseJSON.","Feature-detect by providerId in your calling code and choose the structured-output strategy per provider."],"exampleFix":"// before\nawait session.prompt({ text, responseFormat: { type: 'json', schema } }); // codex-cli model\n// after\nif (agentModel.providerId === 'openai-codex-cli') {\n  const { text } = await session.prompt({ text: `${text}\\nRespond with only JSON matching: ${JSON.stringify(schema)}` });\n  const data = safeParseJSON({ text });\n} else {\n  await session.prompt({ text, responseFormat: { type: 'json', schema } });\n}","handlingStrategy":"fallback","validationCode":"function supportsRequiredJsonOutput(providerId: string): boolean {\n  return providerId !== 'openai-codex-cli';\n}\nconst useStructured = turnOpts.responseFormat?.type === 'json' && supportsRequiredJsonOutput(agentModel.providerId);","typeGuard":null,"tryCatchPattern":"try {\n  await session.prompt({ ...opts, responseFormat });\n} catch (e) {\n  if (HarnessCapabilityUnsupportedError.isInstance(e) && e.message.includes('openai-codex-cli')) {\n    // fallback: prompt-instructed JSON + safeParseJSON validation\n    await session.prompt({ ...opts, responseFormat: undefined });\n  } else throw e;\n}","preventionTips":["Gate structured-output features on providerId before issuing the turn.","Keep a prompt-based JSON fallback (instruct + safeParseJSON) for providers without external tools.","Document in your harness abstraction which providers support required structured output."],"tags":["structured-output","provider-capability","codex-cli","cline"],"backgroundTag":"provider-capability-unsupported","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}