Repository navigation
Description
User Story
I use OpenShell (0.1.7 on our test cluster, evaluating 0.1.9) as the sandbox runtime behind a multi-tenant agent platform. Our control plane manages every sandbox through the gateway's gRPC API, and lets each tenant review the mechanistic drafts of their agent's blocked connections: list them (GetDraftPolicy), approve or reject them, and clear the pending ones (ClearDraftChunks). Gateway auto-approval is off; the control plane keeps policy authority.
I directly encountered this: long-running agents keep producing drafts, and a sandbox's draft list can grow until it no longer fits in one gRPC response. At that point every draft operation for that sandbox fails, and the only way to remove the rejected drafts is to delete the sandbox.
Problem Statement
A sandbox's draft chunks have no upper bound, no expiry and no paging:
GetDraftPolicyreturns every chunk matchingstatus_filterin a single response.GetDraftPolicyRequesthas nopage_size/page_token, althoughproto/pagination.protoexists.ClearDraftChunksclears pending chunks only. Rejected chunks cannot be removed by any RPC and stay until the sandbox is deleted. This covers both kinds: chunks a reviewer rejected, and chunks the gateway itself rejects ascovered by active policy revision N.crates/openshell-server/src/grpc/policy.rsitself notes that "Pending queues are agent-driven and unbounded".
Impact / Why This Matters
Each pending chunk carries two full copies of the sandbox policy, the current one and the candidate. We measured this on recorded 0.1.7 gateway responses (Kubernetes driver, mechanistic mode):
- A policy endpoint with
allowed_ipscosts about 1.58 KB per copy. - A pending chunk costs about 0.55 KB plus its two policy copies.
So the response size grows with the number of endpoints in the policy times the number of chunks:
| Policy | Chunks that reach 32 MiB |
|---|---|
| 64 single-endpoint rules | about 163 |
| 64 rules × 32 endpoints | about 5 |
| 10 single-endpoint rules | about 1,000 |
Past the client's maximum receive size, the call fails with RESOURCE_EXHAUSTED ("Received message larger than max"). Every operation that has to read drafts for that sandbox then stops working: listing, and approve or reject whenever they read the chunk first. Raising the client's receive limit only moves the cliff, and the gRPC default of 4 MiB is far lower.
What we can do today:
- Clear the pending chunks. This helps only when the pending ones are the problem.
- For rejected chunks, delete and re-create the sandbox. This destroys the workspace volume and the agent's state, so it is not an acceptable way to prune review history.
- A rejected chunk keeps the policy copies from the time of rejection (observed on one chunk). Each distinct rejected
host:portadds one chunk that stays for the life of the sandbox.
Proposed Design
From an API client's point of view:
- Paging for
GetDraftPolicy. Addpage_sizeandpage_token, reusingpagination.proto, with a stable order such asfirst_seenand then id. A client can then list any number of chunks with the default receive limit. - A way to remove non-pending chunks. For example, a
status_filteronClearDraftChunks(pending,rejectedor all), or a delete of one chunk by id. Keep today's behaviour that a cleared connection which is blocked again produces a new chunk. - Optional bounded retention. A gateway setting caps chunks per sandbox and/or expires rejected chunks after an age, and pruning is observable through a log or OCSF event.
- Optional compact listing. A list mode that omits the two full policy copies (for example
include_policy_snapshots: false), so a list stays small and a client fetches one chunk in full only when reviewing it.
Notional examples:
GetDraftPolicyRequest { sandbox, status_filter: "rejected", page_size: 100, page_token }
ClearDraftChunksRequest { sandbox, status_filter: "rejected" }
openshell rule get <sandbox> --status rejected --page-size 100
openshell rule clear <sandbox> --status rejected
Acceptance Criteria
- A sandbox with any number of draft chunks can be listed completely by a client that uses the default gRPC receive limit.
- Rejected chunks can be removed without deleting the sandbox. This covers both reviewer-rejected chunks and gateway-rejected
covered by active policy revision Nchunks. - Removing chunks does not change the sandbox policy (version, hash, rules), as with
ClearDraftChunkstoday. - If retention is added, the cap or expiry is configurable and documented, and pruned chunks are observable.
- Clients that do not set the new fields keep today's behaviour.
Alternatives Considered
- Raising the client's maximum receive size: this only moves the limit, because the response grows with the policy size times the chunk count.
ClearDraftChunks: it does not touch rejected chunks.EditDraftChunk/UndoDraftChunk: edit applies to pending chunks, and undo reverses an approval. Neither removes a rejected chunk.- Deleting and re-creating the sandbox: it loses the workspace volume and the agent's state.
- Approving through the gateway: this hands policy authority to the gateway. We keep auto-approval off and apply rules through our control plane. Approved chunks cannot be cleared either.
- Middleware or an interceptor: it could reject or trim a response, but it cannot page through stored chunks or delete them. The gap is in the storage and the RPC shape.
Agent Investigation
We compared v0.1.7 and v0.1.9 through the GitHub API:
proto/openshell.proto: the draft-related lines are identical between the two tags.GetDraftPolicyRequestis still{ sandbox, status_filter, workspace_scope }.ClearDraftChunksRequestis still{ sandbox, workspace_scope, request_id }.
crates/openshell-server/src/grpc/policy.rs: these handlers are line-identical between the tags:handle_get_draft_policyhandle_clear_draft_chunkshandle_approve_draft_chunkhandle_reject_draft_chunkhandle_submit_policy_analysis
MAX_PENDING_REFRESH_PER_POLICY_CHANGE = 32bounds only how many pending chunks are re-evaluated after a policy change. It does not bound how many chunks a sandbox keeps.crates/openshell-server/src/policy_store.rsandcrates/openshell-server/proto/storage.protohave no commits between v0.1.7 and v0.1.9.docs/how-it-works/policies/advisor.mdxdocuments approving and rejecting proposals. It does not mention a limit, retention, paging, or a way to remove rejected proposals.
Checklist
- I've reviewed existing issues and the published docs
- This is a design proposal, not a "please build this" request
Activity