# Agent Unary gRPC contract

`proto/agent/agent.proto` is the project-owned Agent/Dispatcher protocol. It is
not the SaaS/MQ contract and is not evidence of external supplier acceptance.
Both processes use Unary gRPC over mutually authenticated TLS; no audio bytes
or SaaS business requests are carried over these RPCs.

`AgentControlService` exposes only these methods:

- `GetAgentStatus` and `ActivateAgent` probe a deployed Agent and establish its
  active Dispatcher-bound session. Boot ID, epoch, generation, peer certificate
  and approved identity fence stale or self-reported callers.
- `GetLoadedSIP` reads the Agent's observed trunk revisions. A Mock observation
  is not proof that Asterisk actually loaded the configuration.
- `ExecuteApproved` receives a frozen task/SIP/AI decision and exclusive dial
  deadline. The Agent checks the session and signed execution boundary, not
  the Dispatcher's outbound business policy. Unknown execution is never
  originated again just because an RPC response was lost.
- `ApplyApprovedTaskControl` closes task admission before draining or hanging
  up active calls. Pause, resume and stop carry no external command ID or
  revision CAS; stop is irreversible for the same task identity.
- `RequestRecordingUpload`, `ReportCallEnded` and `ReportCallResult` request a
  bounded upload grant, release a confirmed-ended call and deliver its one
  final result. The Agent uploads directly to OSS. The RPC never transfers
  the recording bytes or reports SaaS application receipt.

Task and provider snapshots can contain credentials. Do not log or persist raw
request bodies. `RequestMeta.protocol_version=agent.v1` is a meaningful wire
protocol value, not an implementation-generation label; field numbers are not
reused. Errors, unknown outcomes and recovery boundaries are in `ERRORS.md`.

Generate and verify using the pinned local tools:

```sh
buf lint
buf generate
sh scripts/check-proto.sh
```

The currently registered Agent command supports isolated Mock only. The local
mTLS and Mock tests do not establish real Asterisk, OSS, AI or SaaS acceptance.