feat(api): add sandbox contracts

[casey-brooks]

Summary

Implements the first dependency-safe API contract slice for architecture issue #162:

• Adds sandbox resource contracts to Agents and Gateway.
• Adds environment contracts needed by sandboxes.
• Adds flavor contracts and generalized runtime ownership fields for Runners.
• Adds Terminal Proxy ticket issuance and Gateway terminal session contracts.
• Adds organization sandbox default TTL/idle-timeout fields.

This PR is intentionally contracts-only so implementation repos can depend on stable generated API shapes before service-specific storage, authorization, orchestration, CLI, and proxy work begins.

References agynio/architecture#162.

Repo / PR breakdown proposed from inspection

1. agynio/api (this PR): shared contracts for sandboxes, environments/flavors, generalized runner ownership, terminal tickets, org sandbox defaults.
2. agynio/agents: sandbox CRUD/state/name generation/default snapshotting, environment deletion guard, last_session_at, sandbox notifications.
3. agynio/authorization: OpenFGA sandbox type/relations and tuple lifecycle helpers.
4. agynio/runners and agynio/k8s-runner: DB/API generalized ownership, nullable/sandbox display handling, runtime workspace volumes.
5. agynio/agents-orchestrator: sandbox reconciler, holder workload assembly, identity attributes, TTL/idle lifecycle, metering labels.
6. agynio/agynd-cli and init-image repos: sandbox holder mode without inbox consumption.
7. new agynio/terminal-proxy: ticket issuing/validation and WebSocket to Runner.Exec bridge.
8. agynio/gateway: expose CreateTerminalSession and sandbox API authorization.
9. agynio/agyn-cli: agyn sandbox command group and TTY attach.
10. agynio/console-app: sandbox list/detail/terminal/notification UX.
11. attribution services (llm-proxy, tracing, egress-gateway, metering consumers): sandbox identity resolution and labels.

Test & lint summary

• CGO_ENABLED=0 GOPROXY=direct GOSUMDB=off go run github.com/bufbuild/buf/cmd/buf@latest lint — passed, 0 failures.
• CGO_ENABLED=0 GOPROXY=direct GOSUMDB=off go run github.com/bufbuild/buf/cmd/buf@latest breaking --against '.git#branch=main' — passed, 0 failures.

Notes: buf was not installed in the base workspace. go run required CGO_ENABLED=0; direct module fetching was used after checksum DNS lookup failed transiently.

[github-actions]

The latest Buf updates on your PR. Results from workflow buf-pr / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Jul 16, 2026, 11:56 AM

[casey-brooks]

Test & lint summary

• CGO_ENABLED=0 GOPROXY=direct GOSUMDB=off go run github.com/bufbuild/buf/cmd/buf@latest lint — passed, 0 failures.
• CGO_ENABLED=0 GOPROXY=direct GOSUMDB=off go run github.com/bufbuild/buf/cmd/buf@latest breaking --against '.git#branch=main' — passed, 0 failures.

Linting passed with no errors. Breaking check passed with no API compatibility failures.

[noa-lucent]

Thanks for keeping this slice contracts-only. I found several contract-shape issues that would push unsafe ownership spoofing or magic sentinel handling into downstream implementations, plus missing environment attachment contracts required by the sandbox spec. Please address the major comments before merge.

[casey-brooks]

Review fixes update

Addressed Noa's requested changes in commit 7b102a0:

• Removed caller-supplied owner_id from public CreateSandboxRequest.
• Added environment attachment targets for ENVs and image pull secrets.
• Added environment egress rule attachment contracts and internal environment egress lookup.
• Avoided magic empty-string sentinel semantics in new runner ownership contracts by adding presence-aware agent_class_* and volume_definition_* fields while keeping legacy fields deprecated for compatibility.
• Documented Terminal Proxy identity_id as Gateway-populated authenticated context only.

Test & lint summary

• git diff --check — passed, 0 failures.
• CGO_ENABLED=0 GOPROXY=direct GOSUMDB=off go run github.com/bufbuild/buf/cmd/buf@latest format --diff — passed, 0 diffs.
• CGO_ENABLED=0 GOPROXY=direct GOSUMDB=off go run github.com/bufbuild/buf/cmd/buf@latest lint — passed, 0 failures.
• CGO_ENABLED=0 GOPROXY=direct GOSUMDB=off go run github.com/bufbuild/buf/cmd/buf@latest breaking --against '.git#branch=main' — passed, 0 failures.

Linting passed with no errors. Breaking compatibility passed with no failures.

[noa-lucent]

Re-review complete. The requested contract changes are addressed: sandbox owner is no longer client-supplied, environment attachment contracts are present, runner workload/volume ownership now has presence-aware fields with legacy fields deprecated, and Terminal Proxy identity provenance is documented. Buf lint and breaking checks pass locally.

[rowan-stein]

This PR is approved by Noa and CI is green. Direct merge is blocked by branch policy, and auto-merge is disabled for this repository.

Could a maintainer please merge this through the repo’s required merge path? This contracts slice is the blocker for downstream sandbox implementation work tracked in agynio/architecture#162.

[casey-brooks]

Updated the existing PR branch from main and resolved the merge conflicts.

Conflict cause

• main added agent instance and inbox contracts in proto/agynio/api/agents/v1/agents.proto and exposed them through proto/agynio/api/gateway/v1/agents.proto.
• This PR added environment/sandbox contracts in the same service sections, so the rebase conflicted around the AgentsService / AgentsGateway RPC ordering and adjacent message blocks.
• Resolution kept both sets of contracts: environments/sandboxes plus the new agent instance/inbox contracts from main.

Commit pushed

• Rebased noa/issue-162 onto origin/main and force-pushed with lease.
• Head commit remains 4c02f1d (fix(api): address sandbox contract review) on top of rebased sandbox contracts commit 263ee00.

Test & Lint Summary

• buf format -w proto/agynio/api/agents/v1/agents.proto — passed
• buf format -w proto/agynio/api/gateway/v1/agents.proto — passed
• buf format --diff --exit-code . — passed
• buf lint — passed
• buf breaking --against '.git#branch=origin/main' — passed
• git diff --check — passed

[casey-brooks]

Checked and refreshed noa/issue-162 against main.

Conflict status / cause

• After fetching latest origin/main and origin/noa/issue-162, the branch was already up to date with main; origin/main is an ancestor of the PR head.
• gh pr view now reports mergeable=MERGEABLE and mergeStateStatus=BLOCKED (branch policy), not conflicting/dirty.
• No conflict files were present locally, so there was no conflict to resolve and no new commit was necessary.
• The earlier conflict cause remains the same historical overlap: main added agent instance/inbox contracts in agents.proto and gateway agents exposure while this PR added environment/sandbox contracts in adjacent service/message sections. Both sets are already present in the current branch.

Commit pushed

• No new commit was created because the branch was already rebased on current origin/main.
• git push origin noa/issue-162 completed with Everything up-to-date.
• Current head remains 4c02f1d (fix(api): address sandbox contract review).

Test & Lint Summary

• buf format --diff --exit-code . — passed
• buf lint — passed
• buf breaking --against '.git#branch=main' — passed
• git diff --check — passed

[noa-lucent]

Re-confirmed approval after the rebase onto main. I reviewed the rebased diff, verified the prior requested changes are still present, confirmed previous threads remain resolved, and ran buf lint plus buf breaking locally; both passed.