✨ feat(contracts): declare action scope and mutability (#92)

[alain-sv]

Closes #92.

V2AgentCapabilities.actions was a flat list[str] of opaque identifiers, so consumers had no declared way to know whether an action mutates or what it is scoped to. Studio inferred both by pattern-matching the identifier — including for authorization, where the identifier is caller-supplied.

Change

class V2ActionDefinition(ContractModel):
    id: str
    mutating: bool = True                                     # changes agent-side state?
    scope: Literal["workspace", "mission", "job"] = "job"      # context it operates within


class V2AgentCapabilities(ContractModel):
    actions: list[V2ActionDefinition] = Field(default_factory=list)

Plus V2DatasetDefinition.scope (mirroring V2ResourceDefinition.scope) and V2AwaitingState.reopenable: bool = False.

The builder derives metadata from the definition each action comes from:

source	scope	mutating
actions= (explicit)	as declared	as declared
resources	V2ResourceDefinition.scope	True
datasets	V2DatasetDefinition.scope	False
job_policy.sync	job	True
job_policy.setup.preview_action	job	False
job_policy.setup.start_action / submit_action	job	True
workspace binding	workspace	True
agent methods	job	True

Precedence is explicit > derived > bare: an explicit V2ActionDefinition in actions= overrides the derived metadata, while a bare id string declares nothing and defers to the definition it was derived from. First mention fixes the order in either case.

Compatibility

Plain strings are still accepted everywhere a list of actions is taken — build_v2_agent_registration(actions=[...]) and registration payload validation alike — and coerce to mutating=True, scope="job", the fail-closed reading that matches current behaviour. Existing agents need no change.

Only the serialized form moves: capabilities.actions now emits objects. Studio must accept both shapes on ingest, because agents pinned to older Supervaizer releases keep sending bare strings regardless of what this repo emits. No protocol version discriminates the two — versions.a2ui_version and versions.a2a_version cover the surface catalog and the A2A protocol, not the registration payload — so type-sniffing is the contract, not a temporary migration step.

Deviations from the issue

• Reuses the existing 3-value scope. The proposed Literal["job","mission","agent","resource","dataset","workspace"] mixed context with object kind; V2ResourceDefinition.scope already exists as Literal["workspace","mission","job"]. Finding 2 does not need the kind axis: the job-method predicate is mutating and scope == "job", which excludes dataset.*.query (non-mutating) and workspace-scoped resource operations while keeping a job-scoped resource.invoice.reconcile — the case the current prefix denylist gets wrong.
• Structured on the wire, union only on input. list[str | V2ActionDefinition] would push a type branch onto every consumer permanently.
• mutating is not derived for resource operations. V2ResourceDefinition.operations is freeform list[str]; inferring mutability from "list" / "read" would be the same string-matching this issue is about.
• Dropped label and surface from V2ActionDefinition — no finding needs them.
• Finding 4 needs no supervaizer change. _is_job_analytics_surface(surface) == "job.analytics" dissolves once Studio checks per-action mutating instead of per-surface name.

Caveat on finding 1

mutating does not close the authorization hole on its own — the agent still declares its own capabilities. What changes is when and from what: declared once at registration and checked server-side against the stored registration, instead of parsed from a per-request caller string. If Studio authorizes against capabilities echoed in the request, the hole survives.

Not addressed

src/supervaizer/examples/local_server.py lists job.start.preview as a bare action and declares no job_policy.setup, so the reference agent still ships that action as mutating=True. Correct under the fail-closed default, but the example does not demonstrate the read-only path.

Verification

696 tests pass, mypy and pre-commit clean, model reference and OpenAPI regenerated.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WhJTvFEwmL8L1ZXCxj4Roj

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b3d1a1b86a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Preserve explicit metadata when duplicate IDs mix forms

When actions contains both a structured definition and a legacy string for the same derived action ID—a likely incremental migration pattern—bare_ids marks the ID as bare regardless of which declaration won resolved.setdefault. The derived entry then overwrites the explicit metadata here; for example, [V2ActionDefinition(id="resource.r.op", mutating=False), "resource.r.op"] plus the matching resource silently becomes mutating and resource-scoped, contrary to the documented explicit-over-derived precedence. Track whether the retained declaration itself was bare, or reject the inconsistent duplicate explicitly.

AGENTS.md reference: AGENTS.md:L10-L10

Useful? React with 👍 / 👎.

[alain-sv]

Confirmed and fixed in 593c43b. Reproduced before the fix:

build_v2_agent_registration(
    ...,
    actions=[V2ActionDefinition(id="resource.r.op", mutating=False, scope="job"), "resource.r.op"],
    resources=[V2ResourceDefinition(id="r", label="R", scope="workspace", operations=["op"])],
)
# -> [('resource.r.op', True, 'workspace')]   explicit metadata silently lost

_merge_actions now coerces the declared entries itself and records bareness per retained declaration, rather than from a set built over the raw input.

Went one step past the report: precedence is about metadata, not position, so an explicit definition also upgrades an already-retained bare id — an id declared both ways keeps the explicit metadata regardless of which form appears first, while the earlier mention still fixes the order. Chose that over rejecting the duplicate because it makes the documented explicit > derived > bare rule hold unconditionally instead of adding an error path for an authoring pattern that has a sensible reading.

Covered by test_v2_mixed_action_forms_keep_explicit_metadata, parametrized over both orderings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 593c43b723

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Mark workspace binding options as non-mutating

When bind_existing is enabled, this marks workspace_binding.options as mutating even though the workspace-binding protocol defines that action as only listing existing agent-side records. Consumers using the new flag for authorization or filtering will consequently hide or deny this read-only operation; emit mutating=False for existing while retaining True for create.

AGENTS.md reference: AGENTS.md:L10-L10

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Reject conflicting explicit action definitions

When actions contains two structured definitions with the same ID but different mutating or scope values, the second definition falls through this branch and is silently ignored, leaving authorization metadata dependent on input order. Fresh evidence in the final tree is that mixed bare/explicit duplicates are now handled, but explicit-to-explicit conflicts still have no check; reject the inconsistent contract with a clear validation error instead.

AGENTS.md reference: AGENTS.md:L10-L10

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9763bbdf9b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Mark job sync as non-mutating

When Studio gates actions using the new mutating metadata, this advertises job.sync as requiring write access even though the v2 protocol defines it as returning a convergent state snapshot (docs/2026_05_SUPERVAIZER_v2.md:376). Read-only operators can consequently lose status refresh and catch-up functionality; emit mutating=False for this derived action.

AGENTS.md reference: AGENTS.md:L10-L10

Useful? React with 👍 / 👎.