feat(ai): support constrained sampling

[mitsuhiko]

This adds an opt-in constrainedSampling config for tools so callers can request provider-side constrained tool input generation.

Basically tools can now ask the model provider to constrain tool arguments in two ways:

• JSON-schema constrained sampling which is typically exposed as strict tool calling:
  • strict: "prefer" uses strict provider behavior when available and falls back otherwise.
  • strict: "require" fails clearly if the selected provider/model cannot honor it.
• Grammar-constrained sampling for OpenAI tool calls, using OpenAI Lark or regex grammar variants.

Now there are some notes here that this PR does not address today. One of the motivations for prefer over true/false is that if you define too many tools to be strict, inference APIs can fail. The motivation here is that we can later (not done today) be more clever in how we deal with strictness. For now that's just over-engineering.

The second note is that only OpenAI today supports constraining for tool calls with custom grammar and it's unclear what other APIs will do in the future. Quite a few inference APIs support constraining on some grammar for regular responses for structured completions but that's not really applicable for pi today.

Because I do not want to design some feature around some OpenAI oddity the change here detains grammar-constrained tools to be like ordinary pi tools to callers: for custom grammar tools we use a normal object schema with one required string property. The idea here is that for providers without native grammar support we have a clear way to fall back to the normal JSON/function tool form. Custom providers and model configs can also declare whether they support strict tools or grammar tools, so pi does not assume that every OpenAI-compatible or Anthropic-compatible endpoint accepts these newer fields.

This all came out of the edit-tool investigation in #6278. Newer Claude models can sometimes produce semantically correct nested tool arguments with extra invented fields, especially in long agentic histories. To support apply_patch and other things from OpenAI the entire approach really only makes sense if you consider it as a free form tool so that's where the desire came in to support these grammars.

My experiments show that strict/constrained decoding can eliminate that class of failure and I want to put us into a position where we or users can use OpenAI specific custom tools as well.

This is what this looks like to the user for just constraining on JSON schema:

const strictJsonTool: Tool = {
  name: "edit_file",
  description: "Edit a file by replacing exact text.",
  parameters: Type.Object(
    {
      path: Type.String(),
      oldText: Type.String(),
      newText: Type.String(),
    },
    { additionalProperties: false },
  ),
  constrainedSampling: {
    type: "json_schema",
    strict: "prefer",
  },
};

And this is what it looks like with custom grammar for OpenAI only:

const larkGrammarTool: Tool = {
  name: "apply_patch",
  description: "Apply a unified diff patch.",
  parameters: Type.Object(
    {
      input: Type.String({
        description: "Unified diff patch text.",
      }),
    },
    { additionalProperties: false },
  ),
  constrainedSampling: {
    type: "grammar",
    variants: {
      openai_lark: String.raw`
start: /(.|\n)+/
`,
    },
  },
};

For the grammar case, pi still exposes { input: string } as the tool arguments. I also set up the grammar based sampling so that in case some other tool comes around in the future, you can define more than one grammar.

Fixes #6306

[mitsuhiko]

Maybe this field should be called supportsOpenAIGrammarTools.

[badlogic]

yes

[badlogic]

how do we gate this to openai as a provider? how does this work via proxies?

[mitsuhiko]

We enable grammar tools through per-model compat.supportsGrammarTools, not a generic OpenAI-compatible URL check. We only enables it only for known GPT-5+ OpenAI endpoints on known providers I tested. Any proxy stay off by default and must explicitly opt in:

{
  "providers": {
    "my-proxy": {
      "api": "openai-responses",
      "baseUrl": "https://proxy.example/v1",
      "compat": {
        "supportsGrammarTools": true
      },
      "models": [{ "id": "gpt-5.4" }]
    }
  }
}