Skip to content

chore: merge feature/governance into main - #1996

Merged
patriknw merged 41 commits into
mainfrom
feature/governance
Oct 7, 2026
Merged

patriknw merged 41 commits into
mainfrom
feature/governance

Conversation

@patriknw

@patriknw patriknw commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

DO NOT SQUASH

pvlugter and others added 30 commits June 30, 2026 15:47
* feat: enhanced guardrails - API adaptations

* fixme about Future[Decision]

* expose tracing() on guardrail contexts

* wip: bump runtime version v1.6.9-a7cc7f09

* 'decide' instead of 'evaluate'

* call context as guardrail inner interface

call context as guardrail inner interface

* chore: remove Decision static helpers (#1691)
* import some fully qualified references
* update to complete/inconclusive effects
* remove evaluation equals/hashCode
* remove evaluation session context helpers
* agent bindings as set and simplified
* annotation processor validation tests
* update to published runtime snapshot
* update to interaction id based subjects
* ci: invalidate coursier caches by bumping the cache key version
* switch to config-based evaluation bindings only
main's Understanding restructure (#1706) drops concepts/acls.adoc and the
individual use-cases pages; those deletions are taken. The SPIFFE
component-identity material is already covered by sdk/access-control.adoc,
and use-cases/index.adoc carries page aliases for the removed pages.

concepts/governance-and-the-runtime.adoc is retained and listed under
Agentic concepts, as the guardrail, classifier, evaluator, and sanitization
pages reference it.
Merge main into feature/governance
* docs(api): add package-info for the evaluation and ledger packages

* docs(evaluators): document TestLedgerClient for evaluator unit tests

The testkit ships TestLedgerClient, an in-memory LedgerClient for
seeding interaction records, but the Testing section still hand-rolled
an anonymous LedgerClient in the sample. Use TestLedgerClient instead
and point the prose at it.

* docs(autonomous-agents): compile the client and tasks page examples

Replaces the remaining inline code blocks on client.adoc and tasks.adoc with
tagged includes. Lifecycle operations (assign/complete/fail) and task
creation come from nested tags in the publishing and pipeline endpoints.
Operations the sample app performs only through UI indirection (terminate,
suspend/resume, getState, blocking result, notification streams, async
variants, template params, snapshot fields) live in a new test-scope
demo/docs/ClientApiSample.java that compiles but never runs, following the
testing.adoc precedent for test-scope includes.

Also on client.adoc: the getState field tour now lists the real phase values
("idle", "advance", "model", "tools", "stopped") instead of a wrong
subset, documents the optional reason on suspend/terminate, and drops
"spins up" / "release the actor" phrasing per the writing guide.
tasks.adoc's whole-file DeveloperTasks include becomes tag=class so the tag
markers no longer render.

* docs: expand contractions in body text per the writing standards

The overhaul spec's writing standards (now in docs/CLAUDE.md) call for no
contractions in body text. Sweeps every hand-written page across all
modules, expanding contractions in prose while leaving quoted example
content untouched: AI transcripts and sample model output, example chat
prompts, sanitizer input samples, and comments inside code blocks. "Let's
..." sentences are rephrased to imperative or declarative forms rather
than expanded literally.

Excluded: the auto-generated CLI reference (regenerated from CLI help
text), and release notes and security announcements (historical records).

* docs(agents): page-template conformance for the agent and governance pages

Mechanical conformance batch against the structure-template checklist in
docs/CLAUDE.md:

- Add the missing Testing sections: agents.adoc and autonomous-agents.adoc
  summarize the approach and link to their testing sub-pages, and
  guardrails.adoc gains a section describing how guardrails are exercised
  in integration tests (test-scope configuration, TestKitSupport,
  TestModelProvider, GuardrailException in onFailure) — previously no page
  covered guardrail testing at all.
- Add See also sections to all ten agents/ sub-pages, which had none.
- Rename non-self-descriptive headings: "Topics" (autonomous-agents.adoc)
  to "Autonomous agent topics", "Classifiers"/"Evaluators"
  (agents/testing.adoc) to "Testing classifiers"/"Testing evaluators"
  (with the one inbound xref anchor updated), "Compaction" (memory.adoc)
  to "Session memory compaction", "Guardrail of similar text"
  (guardrails.adoc) to "Similarity guardrail", and "Basic Agent
  Structure" (agents.adoc) to sentence case.
- Standardize the "See also" heading to sentence case everywhere; the
  newer pages used "See Also" while ~58 existing pages use "See also".

Deferred to the overhaul's light-touch-up pass: gerund H1 renames on the
agents/ sub-pages (nav-visible) and the narrative first paragraphs that
should become extractable definitions.

* docs(agents): noun-form page titles and extractable first-sentence definitions

The remaining template-conformance items deferred from the previous pass.

Page titles move to noun form per the writing standards: Prompts, Agent
invocation, Session memory, Failure handling, Function tools, Multi-agent
orchestration, Testing (agents/ sub-pages), and Agent definition
(autonomous-agents/defining.adoc). File names and URLs are unchanged; the
nav, inbound xref link texts, and the hand-maintained llms.txt index are
updated to match.

Narrative openings become extractable definitions, so the first paragraph
states what the page's subject is: function tools (replacing the "you may
frequently hear people say" lead), streaming responses (replacing the
chat-app anecdote), and LLM evaluation (leading with what it is instead of
why it is critical). Also drops "essential", "comprehensive", "robust",
and "a ton of" per the no-value-claims and formality rules.

* docs(guardrails): fix xref anchor for the similarity guardrail section

* docs(evaluators): run prettier-java on EvaluatorTestKitSample

* docs(autonomous-agents): keep the concrete values in the client examples

The client page examples are served from ClientApiSample rather than from
the pipeline and publishing endpoints, so they read with literal values —
an assignee address, an approval comment, a rejection reason — instead of
request accessors, while still being compiled.
chore: merging main into governance branch
* chore: renaming WorkflowEvaluator to DurableEvaluator

* fmt
* feat: interactionId in akka.javasdk.agent.Agent.AgentReply

* backward compatibility constructor added

* runtime bump

* fmt

* bom files
* feat: before-model-call guardrail enforcement

* addressing review comments

addressing review comment by redesigning guardrails using specific types

* fix imports

* code review: tail read optimization (drop+convert)

* code review: document that GR must be thread safe

* code review: document lack of 'thinking' and 'attributes'

* core review: renamed tests

* code review: use-for still used for MCP

* code review: move ToolCallRequest

* code review: comment on validateSingleInterface

* code review: tool call id is never null

* code review: use 'override' in ContextImpls

* code review: use 'getLast()' like a pro
* feat: ledger extension to get all evaluations by interaction id

* additional tests fixed

* fixing docs

* fmt

* reverting changes

* fixing CI
(cherry picked from commit d2199c9)
aludwiko and others added 11 commits September 29, 2026 13:04
… interaction kind (#1949)

* feat: one verdict per evaluation record

* feat: evaluation subject with one interaction kind

* runtime bump

* chore: review feedback on single verdict and subject

* build: regenerate artifact BOM for runtime bump
* build: pin runtime 1.6.17-113-756afd3f-SNAPSHOT

Temporary pin to a runtime snapshot that has the control ids on the SPI.
Align the dependency versions with that runtime. Call the current SPI
constructors with the values the deprecated ones used, marked with FIXME.
The runtime now masks a tool result with the model call entries too.
Replace with the released version before merge.

* fix: read the control-id of each guardrail, sanitizer and evaluator entry

* fix: hand the control id of each guardrail, sanitizer and evaluator to the runtime

* test: start the integration service with control ids

* docs: name the control of a guardrail, sanitizer or evaluator with control-id

* test: build the evaluator descriptors where a spec can check the control id

* test: start the integration service with control ids on a class sanitizer and a durable evaluator

* docs: say which controls the runtime records

* fix: reject a control-id on an evaluator binding or in the evaluation defaults

* docs: give control ids a heading and say what the runtime records

* langchain4j 1.20.2
* feat: new Guardrail SPI

* fix(review): code review fixes
…el (#1959)

* feat: record whether a session message is stored as the model was sent it

* feat: persist the sanitized flag of a session message

* feat: hand the sanitized flag to the runtime and back

* fix: store the user message the model was sent

* docs: session memory holds what the model was sent

* test: history stored as sent over two turns

* fix: keep the session memory event constructors without the flag

* docs: leave sanitized false in a message that an interceptor builds

* docs: state the sanitized contract of SessionMemory and the message events

* docs: name the runtime as the sender of the masked text

* test: read an old session memory snapshot as not sanitized

* docs: keep the custom SessionMemory sanitized contract in the javadoc

* test: keep only the sanitized flag round trip of the session memory events

* fix: no sanitized flag on an AI message, the runtime never masks one

* docs: a sanitizer added later does not mask the stored history

* test: read a session memory event stored without the sanitized flag
* akka-runtime 1.7.1
* logback 1.6.4
* slf4j 2.0.20

---------

Co-authored-by: Patrik Nordwall <patrik.nordwall@gmail.com>
* feat: add ModelCallSimilarityGuard and deprecate SimilarityGuard

* fix(review): code review fixes

* simplified guardrails docs

* fix(review): name the uses to move in SimilarityGuard warnings

The `SimilarityGuard` deprecation warning now names the deprecated uses
the entry declares, with `*` expanded. It states that `SimilarityGuard`
will support only the MCP uses, and that the SDK has no replacement for
model-response.

- For "default jailbreak", the warning lists the settings that differ
  from "default model-call jailbreak", so the user can copy them.
- The last line tells the user to remove the agents and agent roles, or
  to keep only the MCP uses in use-for.
- The warning for an agent with both similarity guards gives the same
  advice in place of "Keep only one".

* fix(review): align SimilarityGuard deprecation note with the warning

The `@deprecated` note on `SimilarityGuard` now states the same facts as
the startup warning. It covers model-response and says that
`SimilarityGuard` will support only the MCP uses. The `reference.conf`
comment on "default jailbreak" now limits the deprecation to
model-request.

* fix(review): document the move from SimilarityGuard

The guardrails page gets a migration section. It states which
`SimilarityGuard` uses are deprecated and what replaces each one. It also
explains how to move "default jailbreak" without losing changed settings.
It lists the behaviour that differs after the move: the guard checks the
masked user message, and the service fails at startup on a missing
dataset or an out-of-range threshold.

* fix(review): nits fixes

* moved migration guide
…#1933)

* feat: fail startup on blocking GR for streaming agent

* fix(review): code review fixes

* fix(review): review suggestions

* docs: move TextGuardrail guidance to the migration guide

---------

Co-authored-by: Patrik Nordwall <patrik.nordwall@gmail.com>
* docs: durable evaluators, evaluation record and testing on the Evaluators page

* banner

* docs + fmt

* docs: classifiers page: banner, sanitizer references and wording

* other docs

* fixing docs

* docs: address review of the governance docs

* docs: no governance banner on the sanitization page
@github-actions github-actions Bot added the documentation documentation related label Oct 7, 2026
@wiz-4aec67d814

wiz-4aec67d814 Bot commented Oct 7, 2026

Copy link
Copy Markdown

Wiz Scan Summary

Scanner Findings
Vulnerability Finding Vulnerabilities 1 Critical
Data Finding Sensitive Data -
Secret Finding Secrets -
IaC Misconfiguration IaC Misconfigurations -
SAST Finding SAST Findings -
Software Management Finding Software Management Findings -
Total 1 Critical

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try the Wiz Code extension for VS Code, JetBrains, or Visual Studio.

<groupId>org.apache.opennlp</groupId>
<artifactId>opennlp-tools</artifactId>
<version>2.5.9</version>
<version>2.5.11</version>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Critical Vulnerability Finding

The following vulnerability impacts org.apache.opennlp:opennlp-tools versions <2.5.12: CVE-2026-82617.

It can be remediated by updating to version 2.5.12 or higher.

To ignore this finding as an exception, reply to this conversation with #wiz_ignore reason

If you'd like to ignore this finding in all future scans, add an exception in the .wiz file (learn more) or create an Ignore Rule (learn more).

To get more details on how to remediate this issue using AI, reply to this conversation with #wiz remediate

Suggested change
<version>2.5.11</version>
<version>2.5.12</version>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought we fixed this? If it's still wrong we should have a separate bump PR for it.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@johanandren Wasn't this the reason for https://github.com/lightbend/akka-runtime/pull/5831 ?
That should be included in runtime 1.7.1
Do we need something on the sdk side too?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, the intent was that it would come in transitively, and be 2.5.12 which the runtime depends on. Not immediately obvious why it would be 2.5.11 here. I'll investigate.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Argh.

akka-javasdk doesn't depend on the runtime or the dev runtime which should bring it in, it depends directly on langchain4j 1.20.2 (project/Dependencies.scala), and that version depends on opennlp-tools:2.5.11. So we'd need to pin it to avoid it here.

However
CVE-2026-82617 is a regex denial of service in opennlp-tools. It only affects the built-in EMAIL and URL patterns in opennlp.tools.namefind.RegexNameFinderFactory. Neither the Akka SDK nor the runtime uses opennlp directly. It comes in only through langchain4j, whose single use is DocumentBySentenceSplitter, which relies on SentenceDetectorME and SentenceModel from the sentdetect package. The runtime's SimilarityGuard uses that splitter. In the 2.5.11 jar, nothing outside RegexNameFinderFactory references it, and nothing in sentdetect references namefind. The vulnerable code therefore can't be reached in production, dev mode or tests, even when 2.5.11 is on the classpath.

@patriknw
patriknw merged commit 82128c1 into main Oct 7, 2026
38 checks passed
@patriknw
patriknw deleted the feature/governance branch October 7, 2026 07:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants