This patch tightens generated tool contracts and makes registry-backed tool providers safer during rolling releases.

Model-facing tool JSON is now derived from goa-ai's own naming contract instead of inheriting transport JSON names from shared Goa expressions. That lets public HTTP APIs use their transport casing while generated tool schemas, examples, codecs, field descriptions, and JSON type metadata stay in the model-facing snake_case shape.

What changed:

• Generates model tool schemas and codecs from dedicated model contract attributes, preserving transform-compatible Go field names while exposing snake_case JSON to models.
• Keeps tool-only forced Goa types out of OpenAPI component pools by default while preserving explicit OpenAPI generation metadata.
• Validates agent-as-tool payloads through generated ToolSpec codecs at the runtime boundary, including missing payloads with required fields.
• Tracks registry provider liveness by provider instance so rolling provider releases do not make unchanged toolsets look unhealthy.
• Adds the generated Goa version marker for the registry service.

Compatibility notes:

• Designs that shared lowerCamel public HTTP transport names with model tool fields will now expose snake_case field names to model providers. Update callers/prompts that hand-author tool JSON to use the generated model schema.
• Public HTTP transport casing is not changed by this release.

Validation:

• make lint
• make test
• PR #160 CI passed for build and integration tests.
• PR #161 CI passed for build and integration tests.

This patch keeps server-only controls out of tool payload schemas while preserving rich result sidecars for observers.

Runtime tool calls now strip the reserved server_data payload field before generated codecs, service executors, agent-as-tool prompt rendering, and child run arguments see the JSON. That keeps strict tool contracts stable even when a model includes observer-facing controls in a tool call.

What changed:

• Prevents strict payload decoders from rejecting valid tool calls because of reserved server_data controls.
• Keeps child agent runs from inheriting server-only payload keys in their canonical tool arguments.
• Preserves the existing result-side ServerData sidecar contract for UI artifacts, evidence, and internal tool composition.
• Adds regression coverage for both generated-style activity execution and agent-as-tool invocation.

Validation:

• go test ./runtime/agent/runtime
• PR CI passed for build and integration tests.

What changed

This release makes token-aware history compression work with real agent transcripts that contain tool calls and tool results.

In v0.56.4, goa-ai learned how to compress long histories by exact provider-counted input tokens. That works only if the token counter sees the same request shape the model will see. For tool-using agents, that means the request must include not just messages, but also the tool definitions advertised to the planner.

v0.56.5 closes that gap. Before each planning activity, the runtime now passes the agent's advertised tool definitions into the history policy. Token-aware compression includes those definitions when it asks the model provider to count input tokens.

Why it matters

Providers such as Bedrock validate tool-bearing transcripts as a full model request. If messages contain tool_use or tool_result blocks but the request omits tools, token counting can fail even though the eventual planner request would be valid.

With this release:

• long conversations with tool calls can still use exact token budgets;
• history compression counts the provider-visible request shape, not a partial approximation;
• complete turns remain intact, including user messages, assistant tool calls, and tool results;
• invalid counting support still fails loudly instead of silently dropping context.

Upgrade steps

Update the dependency:

go get goa.design/goa-ai@v0.56.5

No DSL changes are required beyond the v0.56.4 history-compression DSL update. Applications using token budgets should continue to provide a HistoryModel that supports exact token counting.

Included checks

Validated before release:

• PR #155 CI passed: build and integration-tests.
• Local checks: make lint and go test ./runtime/agent/runtime -run 'TestCompress'.

Release range: v0.56.4...v0.56.5.

What changed

This release helps long-running agents keep the right conversation context without exposing provider internals or guessing about model limits.

First, provider-owned paging cursors stay provider-owned. When a tool returns more data than fits in one response, goa-ai keeps the real provider cursor inside the runtime and gives the model a stable continuation reference. The model can still ask for the next page, but raw provider cursors no longer need to appear in prompts, transcripts, streams, or hook payloads.

Second, agents can now declare token-aware history compression. Instead of only saying "summarize after N turns," a design can say when to compress by turns, by input tokens, or both, and can separately say how much recent history must remain exact. The exact tail is always made of complete conversation turns, so user messages, tool calls, and tool results stay together.

Why it matters

• Long chats can keep useful recent context while older turns are summarized.
• Token budgets are counted with the deployed model instead of guessed at design time.
• Bedrock-backed agents use Bedrock's native CountTokens API for exact context budgeting.
• Compression fails fast if the runtime cannot count tokens exactly, avoiding hidden truncation or accidental context loss.
• Applications can override generated compression defaults for each deployment/model without changing the agent design.

DSL and runtime highlights

History compression now uses explicit functions inside History:

History(func() {
    CompressAtMaxInputTokens(120_000)
    KeepMaxInputTokens(40_000)
    KeepMaxTurns(12)
})

Generated configs include HistoryCompression overrides for deployments that need different token or turn budgets.

Breaking changes

The old Compress(triggerAt, keepRecent) history DSL has been replaced by the explicit CompressAt... and KeepMax... functions. Update agent designs that use compression to the new shape.

Upgrade steps

1. Update the dependency:

   go get goa.design/goa-ai@v0.56.4

2. If an agent uses history compression, update its History block to use CompressAtTurns, CompressAtMaxInputTokens, KeepMaxTurns, and/or KeepMaxInputTokens.

3. If token budgets are configured, provide a HistoryModel that supports exact token counting. The Bedrock model adapter supports this through Bedrock CountTokens.

4. Regenerate generated agent code so the new config and registry wiring are emitted.

Included checks

Validated before release:

• PR #151 and #152 CI passed: build and integration tests.
• Main branch CI for d9e35e1 passed: build, lint, unit tests, and integration tests.
• Local checks for the compression changes: make lint and make test.

Release range: v0.56.3...v0.56.4.

What changed

This release makes Bedrock-backed agents easier to upgrade and safer to run in long tool loops.

First, goa-ai now understands newer Opus 4 model IDs by reading the version from the model ID instead of waiting for a code change for each new compatible release. That means applications can move to the next compatible Bedrock Opus 4 model without the runtime accidentally sending old request settings that the provider no longer accepts.

Second, provider pagination cursors now stay private. When a tool result needs to be continued later, goa-ai gives the model a stable continuation reference instead of exposing the provider's raw cursor. The runtime keeps the real cursor internally and can replay the provider call when the continuation is used.

This release also includes the Goa v3.28.0 dependency update.

Why it matters

• Bedrock model upgrades are less brittle. New compatible Opus 4 IDs follow the same adaptive-thinking and sampling-parameter rules automatically.
• Long-running tool workflows leak less provider detail into prompts, transcripts, streams, and hooks.
• Models still get a simple way to continue paginated results, while applications keep tighter control over provider-owned state.

Breaking changes

No intentional breaking changes.

Upgrade steps

1. Update the dependency:

   go get goa.design/goa-ai@v0.56.3

2. If you use Bedrock Opus 4 models, no planner changes are required. Configure the new model ID in your application; goa-ai will keep the request shape provider-safe.

3. If your tools return paginated results, prefer the runtime continuation references over exposing provider cursors directly.

Included checks

Validated before release:

• Pull request CI for #149 and #150 passed: build and integration tests.
• Main branch CI for ba5c926 passed: build, lint, unit tests, and integration tests.
• Local checks: make test and go test ./features/model/bedrock.

Release range: v0.56.2...v0.56.3.

What changed

This patch makes forced tool-use turns feel boring again, in the best possible way.

When a planner says "the next assistant turn must call a tool," goa-ai now keeps that contract intact while encoding requests in the shape Anthropic and Bedrock actually accept. Anthropic models reject thinking/reasoning mode when tool_choice requires tool use, whether the request names one exact tool or says "call any tool." The Anthropic and Bedrock adapters now own that provider rule directly: they preserve the forced tool choice and omit thinking for that request.

The release also carries structured RunInput.Metadata into run.Context, giving application planners a first-class place for run-scoped state without squeezing domain data into string labels.

Why it matters

• Task and workflow agents can force progress or completion tools without accidentally sending an invalid Anthropic/Bedrock request.
• Planners stay focused on intent: ToolChoiceModeAny means "continue through tools," and ToolChoiceModeTool means "call this exact tool." Provider adapters handle the transport details.
• Applications can pass typed, run-start metadata to planners through the runtime context instead of inventing label encodings.

Breaking changes

No intentional breaking changes.

One compatibility note: run.Context has a new Metadata map[string]any field. Code that constructs run.Context with keyed fields keeps working. If you have unkeyed struct literals, switch them to keyed literals; that is the safer style for exported runtime structs anyway.

Upgrade steps

1. Update the dependency:

   go get goa.design/goa-ai@v0.56.2

2. If your planner needs run-scoped structured state, pass it with RunInput.Metadata and read it from RunContext.Metadata.

3. No planner changes are needed for forced tool-choice thinking compatibility. Keep using ToolChoiceModeAny or ToolChoiceModeTool; the Anthropic and Bedrock adapters now make those requests provider-safe.

Included checks

Validated locally before release:

• make lint
• make test

Release range: v0.56.1...v0.56.2.

This patch tightens the new strict JSON contract introduced in v0.56.0.

Generated union decoders now reject unknown fields in both the {type, value} envelope and the selected branch payload. This closes a gap where payload roots were strict but nested union branch values could still silently ignore stale or misspelled fields.

Upgrade notes

• Regenerate downstream Goa AI artifacts after upgrading from v0.56.0 to v0.56.1.
• If a model/tool payload was sending extra fields inside a union branch, generated codecs now reject it instead of dropping those fields.
• No runtime API changes are required from v0.56.0; this is a generator correctness patch.

Validation

• make lint
• make test

What changed

This release makes tool JSON contracts crisp end to end. Goa-authored tool schemas and examples now travel through generated specs, runtime retry hints, stream events, and provider adapters as canonical raw JSON instead of decoded map[string]any values that each layer might reinterpret differently.

In plain terms: the JSON you define in Goa is now the JSON the model provider sees. Examples stay examples, schemas stay schemas, and repair guidance can point users and models at the exact fields the generated contract expects.

Why it matters

• Generated tool specs now expose schema, example, field description, and JSON type metadata directly. Consumers no longer need to parse JSON Schema at runtime just to explain a missing field.
• Provider adapters receive canonical schema/example bytes, which reduces drift between OpenAI, Anthropic, Bedrock, and custom transport boundaries.
• Tool payload decoding is stricter: payloads with unknown fields are rejected at the generated codec boundary instead of being silently ignored.
• Union payload examples keep their proper envelope, so the model sees a valid one-variant shape instead of an example that only works after special interpretation.

Breaking changes

This is intentionally v0.56.0, not v0.55.6, because several public Go APIs changed.

• planner.RetryHint.ExampleInput has been replaced by planner.RetryHint.ExampleJSON rawjson.Message.
  Manual retry hints must provide a serialized JSON example instead of a Go map.

• model.ToolInputFromSchema now accepts rawjson.Message.
  Boundary code should pass the raw schema bytes it received, not decode them to any and hand the decoded value back to goa-ai.

• tools.TypeSpec schema and example fields now use raw JSON contract values.
  Generated specs emit tools.RawJSON(...) for schema and example fields, and expose FieldDescriptions plus FieldJSONTypes as generated metadata.

• Generated payload decoders now reject unknown payload fields.
  If a tool call previously included extra keys that were ignored, it will now fail validation. Fix the caller or prompt/tool contract to send only the fields declared by the generated payload type. Tool results remain decoded through the result contract path; the strictness is for incoming payloads.

Upgrade steps

1. Update the dependency:

   go get goa.design/goa-ai@v0.56.0

2. Regenerate goa-ai output for every service/toolset that uses the Goa agent DSL.

3. Replace handwritten retry examples:

   data, err := json.Marshal(example)
   if err != nil {
       return nil, err
   }
   hint.ExampleJSON = rawjson.Message(data)

   If your retry hints already come from generated tool specs, prefer the generated example JSON instead of rebuilding it by hand.

4. Update schema transport adapters:

   input := model.ToolInputFromSchema(rawjson.Message(schemaBytes))

   If you are reconstructing a complete provider-neutral contract, use model.ToolInputFromContract so schema, schema-without-root-example, and example JSON stay together.

5. Run your generator tests and any tool-boundary tests. Expect golden files to change where generated specs now use tools.RawJSON(...), generated field metadata, and strict payload decoding helpers.

Included checks

Validated locally before release:

• make lint
• make test

Release range: v0.55.5...v0.56.0.

What changed

This release makes Goa-authored tool examples useful all the way to the model provider. Examples written with Goa Example(...) now become provider-ready tool input examples, including Anthropic and Bedrock input_examples, so agents see concrete, valid payloads beside the schema they must follow.

For readers who are not deep in goa-ai internals: this means the examples you already write in your Goa design can now teach the model how to call your tools. A scheduling tool can show a real schedule request; a lookup tool can show a valid identifier shape; a union payload can show exactly one valid variant. The model gets better guidance without hand-copying examples into prompts.

Why it matters

• Tool examples travel from Goa design, through generated schemas, into provider tool definitions.
• Runtime handoffs now preserve each tool's input contract with ToolInputContract, so boundaries no longer strip the examples and schema details providers need.
• Prompt text stays lean: only authored examples are promoted, and the runtime avoids stuffing generated or synthetic examples into the prompt.
• Bedrock and Anthropic callers receive the same canonical tool input examples instead of provider-specific drift.

Compatibility notes

This is a source-compatible patch release. Consumers should regenerate goa-ai output after upgrading so generated tool specs include the new example projections. Existing tools without authored Goa examples continue to work as before; they simply do not publish provider input examples.

Included checks

• CI passed on main for 841b572.
• Generator, runtime, Bedrock projection, and documentation changes are included.

Patch release for nested agent tool schema generation.

• Preserves canonical discriminated schemas for nested unions inside union variant payloads.
• Keeps repeated shared union definitions idempotent during schema specialization.