[github-actions]

[kagent-dev/kagent#3148 + kagent-dev/kagent#3261](kagent-dev/kagent#3148 and kagent-dev/kagent#3261) — Sandbox guest redesign and scoped Substrate reads

Docs versions: 1.x (first shipped in v1.0.0-rc1)

No code-path rule covers 8 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• .agents/skills/kagent/references/sandboxes.md
• docs/architecture/sandboxes.md
• go/api/client/sandbox.go
• go/core/internal/grpcserver/policy.go
• go/core/internal/grpcserver/sandbox_guest.go
• go/core/internal/service/sandbox/guest.go
• ...and 2 more

What changes for users: The UI's Substrate page is scoped to the controller's watched namespaces. Empty namespace and atespace filters mean all watched namespaces and atespaces on namespace-scoped installs, and filters outside that set return PermissionDenied; cluster-wide installs still read every namespace and atespace. The sandbox guest-service redesign also changes process fields and RPC names, but the dossier did not give an authorized reader page for that API surface.

What the docs now say: The Launch the UI page now explains how namespace-scoped installs affect the Substrate page and clarifies that the Scope tile's all value means all watched namespaces and atespaces in that mode. The sandbox API change is recorded as a placement gap, not drafted into the unrelated MCP, skills, plugins, or UI pages.

Not verified: The configuration was not applied to a cluster, and internal links are unchecked.

How kagent-3148 was drafted, and what was not verified

• Code PR: feat(sandbox): adopt env guest service redesign kagent#3148 and fix(substrate): scope Substrate reads and page tokens to the watched namespaces kagent#3261
• Product: kagent (upstream) -> kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-rc1
• Category: new-feature / issue for #3148; scoped-edit / pr for #3261

Plan, and what changed it

• Planned: Document the sandbox guest-service redesign and scoped Substrate reads on the candidate kagent 1.x pages.
• Learned: launch-ui.md owns the Substrate UI behavior from fix(substrate): scope Substrate reads and page tokens to the watched namespaces kagent#3261, but the feat(sandbox): adopt env guest service redesign kagent#3148 candidate pages cover UI access, MCP tool binding, skills, and plugins rather than sandbox process APIs.
• Did: Updated launch-ui.md for scoped Substrate reads, and downgraded the sandbox process API portion to an issue because no authorized page fits it.

Why a documentation change is necessary

kagent-dev/kagent#3261 changes what a namespace-scoped controller returns to the Substrate page. The existing Launch the UI page says that the page reads WorkerPools, ActorTemplates, Actors, and Workers, and that the Scope tile reads all until a filter is set. Without this update, a reader of a namespace-scoped install might interpret all as every tenant rather than every watched namespace and atespace.

kagent-dev/kagent#3148 changes sandbox process and file API behavior: process responses use state instead of status, exit_code is present only after PROCESS_STATE_EXITED, kill_sandbox_process acknowledges SIGKILL delivery instead of returning a final exit code, and existing sandboxes must be deleted across the guest wire-format change. The candidate pages do not document sandbox process APIs. your-first-mcp-tool.md is about binding Kubernetes MCP tools to an AgentTemplate, about-tools.md is about AgentTemplate tool bindings, plugins.md and skills.md document packaging, and the section index cannot hold configuration or API details.

What changed on disk

• docs-site/content/kagent/1.x/observability/launch-ui.md - explains namespace-scoped Substrate reads and updates the Scope tile description.

How to verify this change

1. Open the kagent UI for an install whose controller watches only selected namespaces.
2. Open Substrate and leave the Kubernetes namespace and ATE atespace filters empty. The page shows only resources from the watched namespaces and atespaces.
3. Set either filter to a namespace or atespace outside the watched set. The page reports a PermissionDenied error.
4. Repeat the empty-filter check on a cluster-wide controller. The page can show resources from every namespace and atespace.

Proposed release note

No proposed-release-note.md: this product has no release-note placement target for this run.

Suggested note for kagent-dev/kagent#3148:

The sandbox guest protocol now uses state for process lifecycle reporting, includes exit_code only after PROCESS_STATE_EXITED, and replaces KillProcess and StreamProcessOutputs with SignalProcess and StreamProcessOutput. Delete existing sandboxes before upgrading because old guest wire-protocol messages are incompatible.

Suggested note for kagent-dev/kagent#3261:

Namespace-scoped kagent installs now scope Substrate summary, actor, worker, and page-token reads to their watched namespaces and atespaces. Requests outside that scope return PermissionDenied or InvalidArgument; cluster-wide installs continue to read all namespaces and atespaces.

What was not verified

• No cluster commands were run in the drafting sandbox. cluster-facts.md records the installed API surface only; no configuration was applied.
• The Substrate UI behavior was not run from this draft. The report uses the dossier's pull request body, diff, tests, and changed functions.
• The sandbox guest-service documentation placement was not verified against pages outside the dossier.
• Hugo was not run, so internal links are unchecked.

How the pages were chosen (triage report)

Feature clusters

These pull requests document one feature between them:

Cluster	Pull requests	Product	Why grouped
c1	kagent-dev/kagent#3148, kagent-dev/kagent#3261	kagent	both are drafted into docs-site/content/kagent/1.x/observability/launch-ui.md, the only page a code-path rule names for one of them, so separate pull requests would conflict

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• feat(outputschema): allow format, pattern and type lists, add opt-in outputSchemaStrict kagent#3284 and fix(substrate): scope Substrate reads and page tokens to the watched namespaces kagent#3261 both have docs-site/content/kagent/1.x/observability/launch-ui.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there

Draft a documentation change

kagent-dev/kagent#3261 — fix(substrate): scope Substrate reads and page tokens to the watched namespaces

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): A kagent install that watches only its own namespace can share a Substrate with other installs. The Substrate API showed it every install's actors and actor templates, and it served another tenant's atespace or namespace when a caller named it. The paging rewrite in #2771 dropped the watched-namespace filter for actors and templates. Page tokens leaked too. ate-api tokens are readable base64 JSON
• Not tested: a cluster was used only to dry-run the YAML manifests the draft added; prose, inline field paths and commands are unrun
• No rule covers 4 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • go/api/gen/kagent/api/v1/system.pb.go
  • go/core/internal/service/system/service.go
  • go/core/internal/service/system/substrate.go
  • proto/kagent/api/v1/system.proto

New configuration: no page mentions it yet

kagent-dev/kagent#3148 — feat(sandbox): adopt env guest service redesign

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): Moves agent-substrate/env to 0d359ea and updates the sandbox gRPC API, Go client, CLI, MCP tools, and generated schema to match the redesigned guest services.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 8 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • .agents/skills/kagent/references/sandboxes.md
  • docs/architecture/sandboxes.md
  • go/api/client/sandbox.go
  • go/core/internal/grpcserver/policy.go
  • go/core/internal/grpcserver/sandbox_guest.go
  • go/core/internal/service/sandbox/guest.go
  • ...and 2 more

Warnings

• feat(sandbox): adopt env guest service redesign kagent#3148: re-drafting because it was named on this run, though its earlier draft is issue. Nothing removes the earlier entry; the new draft replaces it in the ledger when it opens.
• fix(substrate): scope Substrate reads and page tokens to the watched namespaces kagent#3261: re-drafting because it was named on this run, though its earlier draft is issue. Nothing removes the earlier entry; the new draft replaces it in the ledger when it opens.

Draft branch: pr-tracker-draft-kagent-3148-plus1

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. This repository's checks are held as action_required until somebody presses Approve and run on the Checks tab. Checks that come from GitHub Apps rather than Actions, such as DCO, run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[Rachael-Graham]

Covered by #652 (v1.0.0-rc1 docs update).