Skip to content

feat(server): honor execution capability requests in mecak8s - #2816

Open
blkt wants to merge 1 commit into
mainfrom
feat/2712-capability-requests
Open

blkt wants to merge 1 commit into
mainfrom
feat/2712-capability-requests

Conversation

@blkt

@blkt blkt commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • The blanket refusal of execution.template.capabilities is replaced by admission in the shared Service create path, so gRPC and HTTP behave the same. A request is honored exactly or refused, never narrowed.
  • Unknown or repeated names are INVALID_ARGUMENT (invalid_argument). Well-formed requests that cannot be honored are FAILED_PRECONDITION (failed_precondition, HTTP 412) through the new ErrExecutionCapabilityRefused: file-only while it is postponed, --no-shell, a debug target, placements that cannot enforce a request (local, worktree, microVM, explicit placements), a capability the template does not declare, and an agent-definition ceiling.
  • PlacementBindRequest.Capabilities carries the request to EnsureTemplate through the new Client.EnsureTemplateCapabilities; EnsureTemplate keeps its signature. The provider's admission refusal message is kept for EnsureTemplate refusals (bounded, printable, non-generic) and surfaced as ExecutionCapabilityRefusal; every other provider error stays sanitised.
  • Providers report the admitted set on PlacementBinding.AdmittedCapabilities. The session still records ExecutionCapabilities{Files, Shell}, now stamped as admitted ∩ registered; the reported list stays admitted ∩ registered ∩ bound authority.
  • Factories receive the session's set through ContextWithExecutionCapabilities and omit Shell without foreground-command; the agent-definition root also drops its runner. acquireExecution strips the runner from run environments, and a per-session engine is forced when the shared engine registers tools the session does not have.
  • Resume reattaches with the recorded set and never calls EnsureTemplate; it fails with ErrPlacementChanged if the environment no longer admits the recorded set.
  • /clear and fork successors request the source's recorded set through PlacementSuccessorRequest.Capabilities; ReserveSuccessor refuses anything outside the inherited admitted set. Scheduled fires that borrow the source's environment make the same request and inherit only the source's recorded set. A Shell source on a deployment that now runs --no-shell is refused before /clear cancels the source and before fork or a fire reserves an environment. A successor's recorded set must match its source's; bound authority is not part of that comparison.
  • No legacy-session handling: Kubernetes execution state is purged at upgrade.

Issue relationship

Closes #2712

Type of change

  • Bug fix
  • New feature
  • Refactoring (no behavior change)
  • Dependency update
  • Documentation
  • Other (describe):

Test plan

Baseline checks

  • Linting (task lint)
  • Fast offline test suite (task test): covered by task test:race
  • Pre-review race suite (task test:race)
  • Offline demo (go run ./cmd/mecademo)
  • Markdown changed: docs generation/link checks (task docs)
  • User docs/user-facing behavior changed: site build (task site:build)
  • Guarded engine API affected: compatibility check (task api:check): nothing under engine/ changes
  • Intentional engine API change: task api:update + engine/CHANGELOG.md

Also passing: task check:pr and task sdk:e2e.

Acceptance criteria

  • Resume uses recorded capabilities without re-admission: TestResumeUsesRecordedCapabilitiesWithoutReadmission.
  • /clear and fork request the source's capabilities and go through admission: TestSuccessorsRequestSourceCapabilities, TestSuccessorRefusesUnadmittedSourceCapabilities, TestSuccessorsOfShellSourceRefusedAfterNoShell, TestSuccessorsOfAgentBoundSourceIgnoreAuthority, TestScheduleFiresRequestSourceCapabilities.
  • Through the real factory, a session without foreground-command has no Shell tool and no runner: TestRealFactoryWithholdsShellAndRunnerWithoutForegroundCommand.
  • Refusals with gRPC/HTTP parity: TestExecutionCapabilityRequestsAcrossTransports covers unknown, duplicate, file-only, --no-shell, debug target, non-enforcing placement, undeclared, narrowed by the provider, agent-definition ceiling, and honored. Client forwarding and message handling: TestBindForwardsCapabilitiesAndKeepsAdmissionRefusals.

Changes

File Change
internal/adapter/server/execution_templates.go Request validation, refusals, admitted-set checks, capability context
internal/adapter/server/service.go Create, resume, retry matching, and run-environment hooks
internal/adapter/server/placement.go, placement_successor.go Capabilities on bind and successor requests; successor admission
internal/adapter/executionclient/client.go EnsureTemplateCapabilities, admission messages, successor check, admitted set on bindings
internal/app/build.go, agentdef_root.go, placement.go Factories omit Shell and the runner; --no-shell wiring
cmd/mecak8s/flags.go --no-shell help text
contracts/proto/mecatl/v1/harness.proto Field comment only, regenerated
user-docs/ API references and execution environments page

User-facing change

Clients can now request execution.template.capabilities on Kubernetes deployments. ["filesystem", "foreground-command"] is honored; any request that cannot be honored is refused with a reason instead of the previous blanket INVALID_ARGUMENT. --no-shell deployments refuse requests for foreground-command.

API compatibility

No break and no major or feature identifier change; this is the in-major-2 behaviour the #2692 assessment reserved when #2693 made non-empty requests refuse until this issue. Request and response shapes are unchanged and the proto change is comment-only. A non-empty request was always INVALID_ARGUMENT before, so no client relied on it; now a full request is honored and unsatisfiable ones get FAILED_PRECONDITION with a reason, using an existing error code, so the SDK error list is unchanged. session_capabilities.execution keeps its meaning.

On the private mecatl.execution.v1 API, mecak8s now fills EnsureTemplateRequest.capabilities (no .proto change) and surfaces the provider's admission messages. Upgrade: the provider must include #2706, already merged. Stored session data is unchanged; Kubernetes execution state is purged at upgrade per #2692.

Special notes for reviewers

  • Providers whose ExecutionAccess applies to a session must report AdmittedCapabilities, or resume of a session with recorded capabilities fails with ErrPlacementChanged. The Kubernetes provider does; two test fakes were updated to match.
  • The agent-definition ceiling is checked after the factory builds the engine, so a refused agent-bound create allocates and then rolls back an environment, as any factory failure after Bind already does.

@rdimitrov rdimitrov left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Approving. Admission is checked on the shared create path, so gRPC and HTTP return the same result. The refuse-never-narrow rule holds on create, resume, and successors. The --no-shell check runs before /clear cancels the source. Focused server, executionclient, and app tests pass locally.

I left one non-blocking comment on successor admission.

}
stampExecutionCapabilities(created, engine, binding.Environment)
stampExecutionCapabilities(created, engine, binding.Environment, admitted)
if err := checkEffectiveCapabilities(requested, created); err != nil {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Non-blocking: requested is the source's recorded set (admitted ∩ registered), but this check compares it against the successor's effective set, which also applies bound authority. If a session's authority withholds a tool its engine registers, fork and /clear are refused even though the client never asked for anything.

To reproduce with this PR's own ceilingAgent fixture: create an agent-bound session (WithAgentDefinitionName("reviewer")) with no capability request. The source records {Files:true Shell:true}. Then both ForkSessionSuccessor and ClearSessionSuccessor fail with agent definition "reviewer" does not allow "foreground-command".

The real agent-definition and root factories mint authority from the same catalog they register, so I don't think production can reach this today. It is still an easy trap if authority ever narrows separately. Two possible fixes: request executionSessionCapabilities(source) for successors, or check the successor's recorded set rather than its effective set.

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.

Thanks for the review, I should have addressed this issue.

@blkt blkt self-assigned this Nov 16, 2026
Replace the blanket refusal of `execution.template.capabilities` with
admission through the shared `Service` path. A request is forwarded to
`EnsureTemplate`, honored exactly, or refused with `FAILED_PRECONDITION`
(`failed_precondition`); malformed names stay `INVALID_ARGUMENT`.
Refusals cover file-only requests, `--no-shell`, templates that do not
declare a capability, agent-definition ceilings, debug targets, and
placements that cannot enforce capabilities.

The session records admitted ∩ registered capabilities. Factories get the
set through the context and omit `Shell` without `foreground-command`;
run environments drop the command runner. Resume reuses the recorded set
without re-admission, and `/clear` and fork successors request the
source's set.

This branch was successfully deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Capability requests end to end in mecak8s

2 participants