feat(gateway/sandbox): support arbitrary gateway-to-sandbox runtime settings over SandboxConfig #405

Activity

1. johntmyers

   added

   feat

   on Mar 17, 2026
2. johntmyers commented on Mar 17, 2026

   

   johntmyers

   on Mar 17, 2026

   Last edited by johntmyers

   CollaboratorAuthor

   More actions

   🏗️ build-plan

   Implementation Plan

   Issue type: feat
   Complexity: High
   Confidence: Medium-High — core design decisions are now fixed; remaining work is implementation detail and migration mechanics.

   Review Decisions (Locked 2026-03-17)

   • Global policy semantics: when a global policy is set, all sandboxes consume that policy in its entirety (no merge with sandbox policy).
   • CLI direction: extend existing workflows with --global (avoid separate scope syntax).
   • Migration strategy: perform a direct in-place refactor (no long-lived dual API path) if implementation remains non-user-facing and low-risk.

   Summary

   Refactor sandbox policy polling into a broader settings channel so the sandbox pulls a single settings envelope (policy + keyed settings) from the gateway. Add durable global gateway settings with per-key precedence over sandbox settings, enforce mutual exclusivity for a key at gateway vs sandbox scope, and expose CLI commands for get/set/delete flows with one-setting-per-request semantics. Global policy is treated as a reserved setting and, when present globally, fully overrides sandbox-level policy.

   State Machine (Settings Resolution)

   flowchart TD
       A[Sandbox check-in poll] --> B[Load gateway global settings singleton]
       B --> C[Load sandbox-scoped settings object]
       C --> D[Per-key resolve: global key wins]
       D --> E[Resolve policy: global policy key present?]
       E -->|yes| F[Use global policy payload entirely]
       E -->|no| G[Use sandbox policy payload]
       F --> H[Compose effective response: policy + settings]
       G --> H
       H --> I[Return settings response]
   
       J[CLI: set gateway setting key K] --> K[Prompt: this disables sandbox-level K]
       K --> L[Persist global K + bump global revision]
       L --> M[Sandboxes receive K from global on next poll]
   
       N[CLI: set sandbox setting key K] --> O{Is global K set?}
       O -->|yes| P[Reject with FailedPrecondition]
       O -->|no| Q[Persist sandbox K + bump sandbox revision]
   
       R[CLI: delete gateway setting key K] --> S[Remove global K + bump global revision]
       S --> T[Sandbox-level K becomes effective again]
   

   Loading

   Scope

   • proto/sandbox.proto: Replace policy-only poll payload with settings envelope carrying effective policy + effective settings metadata.
   • proto/openshell.proto: Add/extend setting management RPCs for gateway/global and sandbox scopes (one setting per request).
   • crates/openshell-server/src/grpc.rs: Implement effective settings resolution, global-precedence enforcement, and per-key lock error semantics.
   • crates/openshell-server/src/persistence/mod.rs + crates/openshell-server/src/persistence/{sqlite,postgres}.rs: Add durable models/helpers for global singleton settings and sandbox-scoped settings.
   • crates/openshell-server/src/sandbox/mod.rs (or new settings module): Define settings domain model, merge logic, reserved policy key handling, and revision tracking.
   • crates/openshell-sandbox/src/grpc_client.rs: Refactor polling client to consume settings envelope.
   • crates/openshell-sandbox/src/lib.rs: Replace policy-only poll/apply loop with settings poll/apply loop while preserving LKG behavior for policy failures.
   • crates/openshell-cli/src/main.rs + crates/openshell-cli/src/run.rs: Extend commands with --global for global operations and enforce one-setting-per-request UX.
   • e2e/python/test_sandbox_policy.py (and/or new e2e file): Add end-to-end coverage for precedence, lock behavior, and global-policy propagation.
   • architecture/ + docs/: Update architecture and CLI documentation.

   Implementation Steps

   1. Define settings wire model.

      • Add typed SettingValue envelope and reserved policy key payload.
      • Include key source metadata (GLOBAL or SANDBOX) in effective responses.
      • Keep one-setting-per-mutation requests and deterministic success/failure responses.

   2. Add durable global + sandbox settings persistence.

      • Persist one global singleton settings object (e.g., object name global).
      • Persist sandbox-scoped settings objects keyed by sandbox ID.
      • Track revisions by scope and compute an effective revision for sandbox polling.

   3. Direct in-place poll channel refactor.

      • Convert the existing sandbox poll channel from policy-only to settings envelope semantics in one cutover.
      • Update server and sandbox client/loop together so no user-facing workflow changes.

   4. Implement precedence, locking, and unlock rules.

      • Global key present => sandbox mutation for that key returns FailedPrecondition.
      • Global delete of key unlocks sandbox control for that key.
      • Apply this uniformly to arbitrary settings and the reserved policy key.

   5. Implement global policy-as-setting semantics.

      • Global policy key present => all sandboxes use that global policy payload entirely.
      • Sandbox policy writes rejected while global policy key is present.
      • Deleting global policy key restores sandbox policy management.
      • Reuse existing policy validation/safety checks before persistence.

   6. CLI UX with --global.

      • Extend policy commands with --global (example: openshell policy set --global --policy <file>).
      • Add/extend settings commands using the same --global pattern for key/value operations.
      • Prompt on global set: "This disables sandbox-level management for . Continue?".
      • Add non-interactive bypass (--yes) for automation.

   7. Validation and verification.

      • Server unit/integration tests for precedence, lock rejection, delete-unlock, reserved policy key behavior.
      • CLI parsing and prompt behavior tests for --global and --yes.
      • Sandbox tests for settings poll/apply and policy reload safety.
      • E2E tests for full lifecycle with global takeover and release.

   Test Plan

   • Unit tests:
     • Merge algorithm: global overrides sandbox per key.
     • Conflict guard: sandbox write rejected when global key exists.
     • Delete unlock: removing global key restores sandbox key effectiveness.
     • Reserved policy key: validation and serialization/deserialization.
   • Integration tests:
     • gRPC set/get/delete across both scopes with one-setting-at-a-time success/failure semantics.
     • Policy status behavior remains correct when policy is delivered via settings envelope.
   • E2E tests:
     • Create sandbox with sandbox-level key, then set same key globally; verify effective key source is global and sandbox set returns error.
     • Delete global key and verify sandbox-level value is effective again.
     • Set global policy and verify all active sandboxes consume the global policy on poll.

   Risks & Open Questions

   • Typed setting value encoding (oneof primitives vs structured payload) and long-term extensibility.
   • Exact command naming for non-policy key/value operations (settings vs extending another existing namespace) while preserving --global UX.

   Documentation Impact

   • architecture/: settings control-plane model, precedence rules, and poll-state machine.
   • docs/: --global usage for policy/settings, lockout behavior, and unlock via global delete.

   ---

   Revision 2 — locked global policy replacement semantics, --global CLI direction, and direct in-place refactor strategy from stakeholder feedback
   Revision 1 — initial plan based on expanded UX and scope split from #393
3. johntmyers

   added

   state:review-readyReady for human reviewReady for human review

   on Mar 17, 2026
4. johntmyers

   self-assigned this

   on Mar 17, 2026
5. johntmyers

   added

   state:agent-readyApproved for agent implementationApproved for agent implementation

   state:in-progressWork is currently in progressWork is currently in progress

   on Mar 17, 2026
6. johntmyers

   added a commit that references this issue on Mar 17, 2026

   feat(gateway/sandbox): add global and sandbox runtime settings flow

   ...

   This issue will close once commit ca8ea6b is merged into the 'main' branch.

   ca8ea6b
7. drew

   removed

   feat

   on Mar 18, 2026
8. johntmyers

   added 3 commits that reference this issue on Mar 18, 2026

   feat(gateway/sandbox): add global and sandbox runtime settings flow

   ...

   This issue will close once commit 0f93e18 is merged into the 'main' branch.

   0f93e18

   feat(gateway/sandbox): add global and sandbox runtime settings flow

   ...

   This issue will close once commit 3f6aabf is merged into the 'main' branch.

   3f6aabf

   feat(gateway/sandbox): add global and sandbox runtime settings flow

   ...

   This issue will close once commit 6435850 is merged into the 'main' branch.

   6435850
9. johntmyers

   closed this as completedin #474on Mar 20, 2026