Skip to content

Update stacklok/toolhive to v0.65.0 - #1332

Merged
aponcedeleonch merged 4 commits into
mainfrom
renovate/stacklok-toolhive-0.x
Nov 16, 2026
Merged

aponcedeleonch merged 4 commits into
mainfrom
renovate/stacklok-toolhive-0.x

Conversation

@renovate

@renovate renovate Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

This PR contains the following updates:

Package Update Change
stacklok/toolhive minor v0.64.0 → v0.65.0

After this PR opens, .github/workflows/upstream-release-docs.yml adds source-verified content edits for the new release. For stacklok/toolhive, the same workflow also syncs reference assets (CLI help, Swagger) and regenerates the CRD MDX pages.


Release Notes

stacklok/toolhive

v0.65.0

Compare Source

What's Changed

Full Changelog: stacklok/toolhive@v0.64.0...v0.65.0


Configuration

📅 Schedule: (in timezone America/New_York)

  • Branch creation
    • At any time (no schedule defined)
  • Automerge
    • At any time (no schedule defined)

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Never, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.


  • If you want to rebase/retry this PR, check this box

This PR was generated by Mend Renovate. View the repository job log.


Docs update for toolhive v0.65.0

Note

Silent run — skill produced no content commits. The docs are
likely already up-to-date (e.g. main ahead of pin, or a re-run
after a previous PR for this tag merged). Only the version bump
and refreshed reference assets are included.

At a glance

Upstream stacklok/toolhive v0.64.0 → v0.65.0
Hand-written changes 0 commit(s)
Reference assets unchanged
Gaps 1
Owner @aponcedeleonch - identified from Release-Triggered-By trailer on the tagged commit
Release contributors 4 review requested (see sidebar)
Action required Yes — resolve 1 gap(s), then spot-check prose

Who does what

@aponcedeleonch cut this release and owns this PR: review your own changes, chase the remaining approvals, and merge once they're in. You don't need to wait on a review from anyone listed as having no docs impact below.

Everyone with a review request: the target is a review and approval within 2 business days.

Summary of changes

  • Added SPIFFE client authentication (JWT-SVID and X.509-SVID) for token exchange, with configuration, request examples, and troubleshooting rows, at docs/toolhive/guides-vmcp/delegate-agent-identity.mdx, plus cross-links from the vMCP "Choose a way to get a token" table and the K8s embedded auth server field table and TLS listener section
  • Updated the private_key_jwt assertion rules in docs/toolhive/guides-vmcp/delegate-agent-identity.mdx to cover the fixed 60-second clock-skew margin and the 6-minute exp cap
  • Updated docs/toolhive/guides-vmcp/accept-workload-assertions.mdx: removed the placeholder upstreamProviders workaround, since a JWT-bearer-only configuration is accepted without upstreams
  • Updated the CIMD sections in docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx and docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx to describe serving an expired cached document when a re-fetch fails transiently
  • Added metadata.extra.trace_id and metadata.extra.span_id to the audit field tables in docs/toolhive/guides-k8s/logging.mdx and docs/toolhive/guides-vmcp/audit-logging.mdx
  • Skipped ID-JAG issuance for delegate clients (id_jag targets, id_jag_max_lifetime, actor-token validators): RunConfig or Go-embedder only, no CRD field, and nothing issues an ID-JAG at v0.65.0 (respondWithIDJAG has no non-test caller)
  • Skipped the 1 MiB /openapi.yaml cap and the 4096-key YAML mapping limit (Bound registry openapi.yaml read and YAML decoding cost toolhive#7107, Avoid quadratic YAML decoding of untrusted skill files toolhive#7106): hardening limits that real registries and skill files don't reach
  • Skipped the changed acceptedAudiences default for ID-JAG redemption (Add oauthproto/idjag with the XAA client and server rules toolhive#7103): the plain JWT-bearer default the docs describe is unchanged, and ID-JAG redemption by ToolHive isn't documented yet; the schema reference carries the new wording

Gaps needing human context

SPIFFE client authentication: where workloads get a subject token (PR stacklok/toolhive#7092 by @jhrozek)

The new "Authenticate workloads with SPIFFE SVIDs" section documents the configuration and both SVID authentication paths, verified against source at v0.65.0. What it can't yet explain is the end-to-end workflow for the subject token. Source and tests show the subject token must be a ToolHive-issued access token whose client_id is the SPIFFE clientId or whose may_act.sub names it, and the PR notes that "a SPIFFE-only server has no source for its first subject token unless another issuer shares its signing key." Neither the PR nor the architecture doc says how an operator is expected to get such a token to the workload in a real deployment (for example, alongside an upstream provider, or whether external trustedIssuers tokens are accepted for SPIFFE clients), so the section states only the acceptance rules.

File(s): docs/toolhive/guides-vmcp/delegate-agent-identity.mdx

Helper prompt for local Claude:

In docs/toolhive/guides-vmcp/delegate-agent-identity.mdx, the "Subject tokens for SPIFFE clients" subsection (added for stacklok/toolhive#7092) describes which subject tokens a SPIFFE client may exchange but not where a workload gets one. Using the answer I give you below, add 2-4 sentences describing the intended workflow for obtaining that subject token (for example, a user signs in through an upstream provider and the agent receives a token with may_act naming its client ID), and state whether a SPIFFE client can also exchange tokens from an external trustedIssuers entry. Verify any claim against stacklok/toolhive at v0.65.0 before writing it. The workflow is: .

Review routing

GitHub could not request the upstream contributor directly, so review went to the human merger of each relevant upstream PR:

Run cost

Session Turns Cost (USD)
Generation 79 $6.7297
Editorial review 22 $0.6887
Total 101 $7.4184
How this PR was built

Two Claude Opus sessions run per release: a generation pass
(upstream-release-docs skill, 6 phases) followed by a fresh-
context editorial pass (docs-review). Prettier/ESLint
auto-fixes are applied after.

Auto-synced paths — do not hand-edit these in review:

  • static/api-specs/
  • docs/toolhive/reference/cli/ (toolhive only)
  • docs/toolhive/reference/crds/

If a "Gaps needing human context" section is present above,
each entry includes a paste-ready Helper prompt for local
Claude
a reviewer can use to resolve the gap.

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
@renovate renovate Bot added the autogen-docs Pull requests generated by automated release workflows label Nov 13, 2026
@vercel

vercel Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs-website Ready Ready Preview Nov 14, 2026 4:25pm UTC

Request Review

@stacklok-octosts
stacklok-octosts Bot marked this pull request as draft November 13, 2026 14:57
@github-actions

Copy link
Copy Markdown
Contributor

Generating docs for toolhive v0.65.0… (run)

@github-actions

Copy link
Copy Markdown
Contributor

Claude generation report

Session status: success · Workflow run

I updated the v0.65.0 docs and the site builds cleanly. The edits are formatted and linted but not committed; I left that to the later workflow step.

What I changed:

  • guides-vmcp/delegate-agent-identity.mdx (Allow clock skew on private_key_jwt assertions toolhive#7088): private_key_jwt client assertions now allow 60 seconds of clock skew, and exp can be at most 6 minutes ahead. I added that, rewrote the list of rejection causes to point at those limits, and updated the troubleshooting row. I checked both numbers against the constants in pkg/authserver/server/provider.go at the tag.
  • guides-k8s/embedded-auth-server-k8s.mdx (Serve the cached CIMD client when a re-fetch fails transiently toolhive#6857): when a cached CIMD client document expires and the host is temporarily unavailable, ToolHive now keeps using the expired entry. That lasts up to the access token lifespan (default 1 hour). Failures like a 404 remove the entry instead. I added this, confirmed in source that the window is the access token lifespan.
  • CIMD troubleshooting in that page and in guides-vmcp/embedded-auth-server-vmcp.mdx: I explained the fallback=expired_cache and fallback=none values on the CIMD document fetch failed log line. Both log strings exist in source.

What I didn't document, and why:

Files for the workflow:

  • REVIEWERS.json: jhrozek and alex-feel are marked for review, each with a note on what to check. reyortiz3 and rdimitrov are not, with the reasons above.
  • SUMMARY.md: lists the edits and the skipped items.
  • GAPS.md: has the SPIFFE entry.
  • No NO_CHANGES.md, since there were doc changes.

The upstream clone wasn't readable from this session, so I verified against source at the tag with gh api. I didn't run the /docs-review skill on the edits; I reviewed the diff myself instead, since the changes are small.

@github-actions

Copy link
Copy Markdown
Contributor

Claude editorial review report

Session status: success · Workflow run

I reviewed the release docs and fixed one thing: a troubleshooting tip in delegate-agent-identity.mdx gave the wrong time window for one field.

What I reviewed: The HEAD commit only touches generated files you told me not to edit (Helm reference pages and static/api-specs/), and the commit before it only changes .github/upstream-projects.yaml. The actual docs content is in uncommitted changes to three pages, so I reviewed those:

  • docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx
  • docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx
  • docs/toolhive/guides-vmcp/delegate-agent-identity.mdx

Fact checks: I couldn't read the local upstream clone (access was blocked), so I checked against the upstream repo with gh instead.

  • Fallback when a client metadata host is down (cimd_decorator.go, docs/arch/11-auth-server-storage.md): correct. That covers which failures keep using an expired cache entry (timeouts, connection failures, 5xx, 408, 429), the limit of one access token lifespan past expiry (default 1h), removal of the entry on other failures, and the CIMD document fetch failed warning with fallback=expired_cache or fallback=none.
  • Clock skew for private_key_jwt assertions (upstream PR #7088): the new body text is correct. It allows 60 seconds of skew on exp, iat, and nbf, caps exp at 6 minutes ahead, still allows each assertion only once, and keeps the response at HTTP 401 invalid_client.

The fix: The troubleshooting row for HTTP 401 invalid_client said exp, nbf, and iat must all be "within 60 seconds of the server clock." That's wrong for exp, which can be up to 6 minutes ahead, and it contradicted the next clause. It now says:

that exp is no more than 60 seconds past and at most 6 minutes ahead of the server clock, that nbf and iat are no more than 60 seconds ahead of it

This matches the page's body text. Nothing else in the three pages needed changing. I found no other pages that still describe the assertion time limits.

I ran npm run prettier:fix, which reformatted only delegate-agent-identity.mdx (the table column widths), and npm run eslint:fix, which reported nothing. All changes are still uncommitted.

@github-actions

Copy link
Copy Markdown
Contributor

Done · 81 turns · $2.55 · run · see PR body for details

@github-actions

Copy link
Copy Markdown
Contributor

Caution

Docs augmentation failed. Run log.
Retry: gh workflow run upstream-release-docs.yml -f pr_number=1332

@danbarr danbarr closed this Nov 14, 2026
@danbarr danbarr reopened this Nov 14, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Generating docs for toolhive v0.65.0… (run)

@github-actions

Copy link
Copy Markdown
Contributor

Claude generation report

Session status: success · Workflow run

I updated the docs for ToolHive v0.65.0 but couldn't commit. The git add call needed approval, so the six edited pages are still uncommitted in the working tree. The production build passed, and Prettier and ESLint ran clean after the last round of edits.

Doc changes:

  • SPIFFE client authentication (Authenticate clients with SPIFFE X.509-SVIDs toolhive#7092): this used to be rejected at startup. It now works when the trust bundle comes from a file in a ConfigMap. I added a section "Authenticate workloads with SPIFFE SVIDs" to guides-vmcp/delegate-agent-identity.mdx. It covers:

    • the configuration fields
    • token requests using a JWT-SVID and using an X.509-SVID
    • the requirement that TLS reach port 8443 directly for X.509, and using JWT-SVIDs behind an ingress that ends TLS
    • which subject tokens are accepted, and troubleshooting rows

    I linked to it from the "Choose a way to get a token" table in the vMCP guide, and from the field table and TLS listener section of the Kubernetes guide.

  • private_key_jwt clock skew (Allow clock skew on private_key_jwt assertions toolhive#7088): documented the fixed 60-second tolerance and that exp can be at most 6 minutes ahead.

  • Stale workaround removed (accept-workload-assertions.mdx): the "placeholder upstreamProviders" note was wrong. A JWT-bearer-only setup is accepted without upstreams, and source shows this was already true at v0.64.0. The note now says you can omit upstreamProviders, but you then can't set incomingAuth.authzConfig.

  • Cached CIMD documents (Serve the cached CIMD client when a re-fetch fails transiently toolhive#6857): both auth server guides now say that an expired cached document is still served when a re-fetch fails temporarily, and that a permanent failure removes it.

  • Audit events (Record trace and span IDs on audit events toolhive#7102): added metadata.extra.trace_id and span_id to the audit field tables in logging.mdx and audit-logging.mdx.

Left undocumented (recorded in SUMMARY.md):

  • ID-JAG targets, issuance and actor-token validators: they aren't in any CRD, and nothing issues an ID-JAG in this release.
  • The new limits on YAML file size and key count.
  • The changed acceptedAudiences default, which only affects ID-JAG redemption.
  • I also didn't act on one review suggestion, to recommend an issuer on port 8443 for X.509 setups, because source doesn't say which is intended.

Artifacts at the repo root:

  • REVIEWERS.json: jhrozek, reyortiz3, alex-feel and rdimitrov are marked as needing review, each with the commit SHAs and a short note. rdimitrov's changes only add new error messages, but I marked them for review to be safe. The release owner aponcedeleonch is marked as not needing review because they authored no commits in this release.
  • GAPS.md: one entry for @jhrozek. The docs don't yet say how a SPIFFE workload gets its first subject token in a real deployment, and neither the PR nor the upstream design doc explains it.
  • SUMMARY.md.

@github-actions

Copy link
Copy Markdown
Contributor

Claude editorial review report

Session status: success · Workflow run

I reviewed the six docs pages changed for the toolhive v0.65.0 release and made one round of fixes, all in delegate-agent-identity.mdx. Prettier and ESLint both ran cleanly afterwards. I haven't committed or pushed anything.

The commit at HEAD changed only auto-generated files (the Helm reference pages and static/api-specs/), which I left alone. The edits that needed review were the uncommitted ones in:

  • docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx
  • docs/toolhive/guides-k8s/logging.mdx
  • docs/toolhive/guides-vmcp/accept-workload-assertions.mdx
  • docs/toolhive/guides-vmcp/audit-logging.mdx
  • docs/toolhive/guides-vmcp/delegate-agent-identity.mdx
  • docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx

Fixes in the new "Authenticate workloads with SPIFFE SVIDs" section:

  1. The example contradicted the page. The page says ToolHive logs a startup warning when X.509 workload certificates (spiffe_x509) are enabled and the issuer isn't on port 8443. But the example config enabled X.509 with issuer: https://vmcp.example.com, so copying it would trigger that warning. I changed the example's issuer to https://vmcp.example.com:8443 and pointed the JWT-SVID curl example at the same URL. That matters because a JWT-SVID's audience must equal the issuer exactly.
  2. The warning is now an instruction. The paragraph now tells readers to set the issuer to port 8443 on a host the listener certificate covers, and says a startup warning is logged otherwise.
  3. Expanded an acronym. SVID is now spelled out as "SPIFFE Verifiable Identity Document (SVID)" on first use.

Claims I checked: I compared the SPIFFE claims against the merged upstream PR (stacklok/toolhive#7092). They match: only the file bundle source works, servers with no upstream run token-only, certificate chains are capped at four, the bundle goes stale after 24 hours, and JWT-SVIDs must expire within 6 minutes.

I couldn't find the issuer-port warning in that PR's description, and I couldn't search the local upstream clone because it's outside the directories this session can read. Fixes 1 and 2 rely on the earlier session's wording for that warning. The 60-second clock-skew numbers and the new token-only wording in accept-workload-assertions.mdx weren't checked against source either.

The other pages needed no changes: the audit-log trace and span ID fields, the CIMD rule that keeps serving an expired document while the refresh fails, the new row in the "Choose a way to get a token" table, and removing the old upstreamProviders workaround note.

@stacklok-octosts
stacklok-octosts Bot marked this pull request as ready for review November 14, 2026 05:41
@github-actions

Copy link
Copy Markdown
Contributor

Done · 101 turns · $7.42 · run · see PR body for details

rdimitrov
rdimitrov previously approved these changes Nov 14, 2026
SPIFFE clients can exchange subject tokens from a trusted external
issuer, not only from ToolHive. The delegate agent identity guide
described only the ToolHive-issued case, so readers configuring an
external issuer had no guidance on the policy fields needed.

Describe both cases, link to the issuer policy setup, and warn that
allowedDelegateClients set to ["*"] admits every SPIFFE client. Update
the embedded auth server pattern table to match.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
@jhrozek

jhrozek commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

Pushed a docs commit (66ed7bc) on top of this branch.

What changed: the delegate agent identity guide only described SPIFFE clients exchanging ToolHive-issued subject tokens. SPIFFE clients can also exchange tokens from a trusted external issuer, so the guide now covers both cases and links to the issuer policy setup. The embedded auth server pattern table is updated to match.

Why: readers configuring an external issuer had no guidance on the policy fields they need. The guide also now warns that allowedDelegateClients: ["*"] admits every SPIFFE client, so listing specific client IDs is the safer setting.

@jhrozek jhrozek left a comment

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.

Approving. The docs changes match the SPIFFE and issuer policy behavior described in the guide.

@aponcedeleonch
aponcedeleonch merged commit 4c090cd into main Nov 16, 2026
10 checks passed
@aponcedeleonch
aponcedeleonch deleted the renovate/stacklok-toolhive-0.x branch November 16, 2026 13:11

This branch was successfully deployed

1 active deployment
Preview — 66ed7bce Deployed Nov 14, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

autogen-docs Pull requests generated by automated release workflows

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants