docs(runner): classify all protocol actions

This commit is contained in:
Dotta committed 2026-08-21 09:36:56 -05:00
1 parent 057b901240
commit 3c13837c62
1 file changed
+50
@@ -30,6 +30,56 @@ The generated action metadata currently says `realServiceBinding: unbound` and `
| Secrets | `list_secret_metadata`, `read_secret_value` | secrets service; metadata/value claims separated and output redacted | protocol-only/scenario mock |
| Escape hatch | `generic_api_request` | no production binding planned until a narrow allowlist is designed | test-only |
## Per-action production disposition
This is the exhaustive 41-action decision ledger. “Withheld” means the action
is intentionally absent from the agent's authorized catalog; runnerd cannot
invoke an action merely because it exists in the canonical documentation.
| Action | Production disposition | Authority / reason |
| --- | --- | --- |
| `get_task_context` | bound | run/issue/assignee/company join |
| `get_task_history` | bound | issue comments scoped to the bound issue |
| `search_tasks` | bound | `issueService.list`, company-scoped |
| `report_progress` | bound | `issueService.addComment`, run-locked receipt |
| `list_documents` | bound | bound-issue document service |
| `read_document` | bound | bound issue + document key |
| `list_document_revisions` | bound | bound issue + document key |
| `write_document` | bound | optimistic revision service, run-locked receipt |
| `request_human_input` | bound | existing interaction service; five structured variants |
| `list_agents` | bound | company-scoped, redacted actor projection |
| `get_agent` | bound | company equality, redacted actor projection |
| `list_approvals` | bound | company-scoped approval service |
| `get_approval` | bound | company equality |
| `get_approval_context` | bound | company equality + linked issue projection |
| `answer_status_question` | withheld | needs canonical status-answer/thread semantics in the product service |
| `register_deliverable` | withheld | artifact/attachment ownership and idempotency audit pending |
| `finish_task` | withheld | terminal status belongs to native completion + status arbiter; must not race `paperclip_finish` |
| `block_task` | withheld | route enforces blockers/interactions/approvals/unblock-owner policy not yet factored into a shared service |
| `request_review` | withheld | must use execution-policy transition and review-stage validation |
| `set_dependencies` | withheld | route authorization, cycle/readiness, wake, and activity behavior must remain atomic |
| `create_task` | withheld | bounded-delegation policy and parent/depth authorization audit pending |
| `request_approval` | withheld | approval creation/linkage and continuation policy audit pending |
| `decide_approval` | prohibited for agent runs | current real service requires a board user principal |
| `comment_on_approval` | withheld | approval visibility, authorship, and audit parity pending |
| `get_workspace_runtime` | withheld | environment/workspace lease scope audit pending |
| `control_workspace_service` | withheld | privileged process control; explicit grant and idempotency design pending |
| `schedule_wake` | withheld | wake ownership, deduplication, and scheduling policy audit pending |
| `administer_company` | withheld privileged surface | no agent grant policy approved |
| `export_company` | withheld privileged surface | bulk data export is board/admin-only |
| `list_company_skills` | withheld privileged surface | skill-administration protocol remains separate from task authority |
| `sync_company_skills` | withheld privileged surface | mutating skill sync requires explicit administration grant |
| `list_projects` | withheld optional read | not yet bound to a run-authorized project projection |
| `list_goals` | withheld optional read | not yet bound to a run-authorized goal projection |
| `list_routines` | withheld privileged surface | routine visibility policy pending |
| `manage_routine` | withheld privileged surface | scheduler administration is not task authority |
| `list_cases` | withheld optional read | pipeline/case grant model pending |
| `upsert_case` | withheld privileged surface | pipeline mutation grant/idempotency audit pending |
| `inspect_operation_result` | withheld | operation receipt lookup/redaction contract pending |
| `list_secret_metadata` | withheld privileged surface | separate metadata claim and audit projection required |
| `read_secret_value` | prohibited by default | secret-value claim, non-persistence, and output redaction require a dedicated path |
| `generic_api_request` | prohibited | no open-ended production HTTP escape hatch |
## Rules for marking a binding complete
An action moves from `unbound` only when all of the following are true: