Skip to content

omm: support the OpenShell v0.1.9 middleware contract - #106

Merged
johnnygreco merged 2 commits into
mainfrom
johnny/omm-openshell-v0.1.9
Nov 19, 2026
Merged

johnnygreco merged 2 commits into
mainfrom
johnny/omm-openshell-v0.1.9

Conversation

@johnnygreco

@johnnygreco johnnygreco commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

omm create could not produce a project for any OpenShell release since v0.1.0. The latest stable release is v0.1.9 (published 2026-11-17). This PR makes omm work with it and adds a repeatable check that proves it against a real gateway.

There were two separate problems:

  1. Generator. Since v0.1.0, supervisor_middleware.proto imports extension.proto. omm downloaded only the one file, so binding generation failed with extension.proto: File not found.
  2. Starters. Both templates implemented the v0.0.86 contract. The contract has since renamed fields, changed Describe, and made protocol negotiation mandatory. v0.1.9 adds streaming HTTP hooks and deprecates the unary request RPC for removal in 0.2.0.

What changed

Generator

  • omm downloads the OpenShell protos that the middleware proto imports, records each in the manifest under proto_imports with its source URL and SHA-256, and compiles them into the Python bindings. An import must be a plain file name; anything else is rejected before a file is written.
  • omm update publishes each generator-owned proto file on its own: it exchanges a file the project already has, adds a new one without replacing anything, and moves out one the contract no longer imports. Each step rolls back if a later one fails. It refuses to overwrite a file in proto/ that it did not record, unless that file is byte-identical to the imported one.
  • omm create requires a contract with service HttpHooks and reports an older release immediately.

Templates (Python and Rust)

  • Describe accepts MiddlewareDescribeRequest, checks the caller's protocol metadata, and returns the service's own (protocol 1.0, contract and HTTP hooks capabilities).
  • Requests go through HttpHooks.EvaluateHttpRequestHook. The starter continues without reading the body. evaluate_http_request_preflight and evaluate_http_request_body are the extension points.
  • The Rust starter builds with tonic's generated default stubs, so it contains no code for RPCs it does not implement.
  • The generated READMEs cover registration, policy attachment, and how to select body inspection.

Verification script

  • scripts/verify-openshell-release.sh downloads a release's gateway and CLI into a temporary directory, generates both starters, and sends sandbox traffic through them.

Decisions

  1. omm create now needs OpenShell v0.1.9 or newer (decided: follow OpenShell's recommendation). The starters use HTTP hooks. OpenShell's v0.1.9 documentation says "New HTTP middleware should implement HTTP Hooks", and its proto marks the unary request RPC as deprecated for removal in 0.2.0. Keeping the unary RPC would have covered v0.1.0 through v0.1.9, but new projects would need a rewrite at 0.2.0. Version 0.0.1 on PyPI still creates v0.0.86 starters (checked).
  2. The script runs a private gateway (decided: acceptable). AGENTS.md says omm must never install or configure OpenShell. The script is separate from omm, keeps everything in its work directory, and uses its own container label, ports, and database.
  3. The manifest gains proto_imports (open for review). Manifests without it still load.

Contract history, from the protos at each tag:

Releases checked Contract
v0.0.85 and earlier no middleware proto
v0.0.86, v0.0.90, v0.0.100 max_body_bytes, Describe(Empty)
v0.0.110, v0.0.115, v0.0.116 max_payload_bytes
v0.1.0 through v0.1.8 imports extension.proto, Describe(MiddlewareDescribeRequest), unary request RPC only
v0.1.9 adds the HttpHooks services, deprecates the unary RPC

Verification

Run on Linux x86_64 with Docker 29.9.1 and uv 0.13.4, using the official v0.1.9 release binaries (checksums verified).

Real gateway, both starters

cd projects/tools/openshell-middleware-manager
scripts/verify-openshell-release.sh --openshell-version v0.1.9

All 30 checks pass in about two minutes with Rust 1.90.0, the starter's declared minimum. The Rust half also passes with Rust 1.100.0.

Check, for the Python and the Rust starter Result
omm create, then omm update, then every check the generated README lists pass
Gateway starts with the starter registered (it calls Describe first and exits on a mismatch) pass
openshell gateway info reports protocol 1.0 with the HTTP hooks capability required pass
Gateway admits a sandbox policy that attaches the starter pass
Request from the sandbox arrives upstream unchanged, HTTP 200 pass
OpenShell logs ALLOWED ... http_event_kind:middleware_invocation ... failed:false pass
With the starter stopped, the same request gets HTTP 403 middleware_failed and never reaches the upstream pass
After a restart, requests pass again pass
Full output
toolchain: cargo 1.90.0 (840b83a10 2025-07-30) | uv 0.13.4 (x86_64-unknown-linux-gnu) | Docker version 29.9.1, build dfc520d
INFO verifying omm against OpenShell v0.1.9 for: python rust
PASS downloaded and checksum-verified the OpenShell v0.1.9 gateway
PASS downloaded and checksum-verified the OpenShell v0.1.9 CLI
PASS omm create --language python --openshell-version v0.1.9
PASS omm update --openshell-version v0.1.9 (python)
PASS python starter: uv sync --locked
PASS python starter: ruff format --check
PASS python starter: ruff check
PASS python starter: ty check
PASS python starter: pytest
PASS python starter: uv build
PASS omm create --language rust --openshell-version v0.1.9
PASS omm update --openshell-version v0.1.9 (rust)
PASS rust starter: cargo fmt --check
PASS rust starter: cargo clippy -D warnings
PASS rust starter: cargo test --locked
PASS rust starter: cargo build --locked
PASS OpenShell v0.1.9 gateway started after Describe on every registered starter
PASS gateway negotiated protocol 1.0 with HTTP hooks for the python starter
PASS gateway negotiated protocol 1.0 with HTTP hooks for the rust starter
PASS built a sandbox image with curl
PASS gateway admitted a sandbox policy that attaches the python starter
PASS sandbox request passed through the python starter unchanged (HTTP 200)
PASS OpenShell logged an allowed middleware invocation for the python starter
PASS OpenShell blocked the request while the python starter was stopped (HTTP 403)
PASS requests passed again after the python starter restarted
PASS gateway admitted a sandbox policy that attaches the rust starter
PASS sandbox request passed through the rust starter unchanged (HTTP 200)
PASS OpenShell logged an allowed middleware invocation for the rust starter
PASS OpenShell blocked the request while the rust starter was stopped (HTTP 403)
PASS requests passed again after the rust starter restarted
ALL PASS omm works with OpenShell v0.1.9 (python rust)

The script fails when it should

Variant Result
Unmodified main FAIL at omm create: extension.proto: File not found
Starter that supports HTTP hooks without requiring them FAIL: the gateway rejects the registration at startup
Starter that denies every request FAIL: the request is not passed through
Tampered gateway archive, or a missing checksum file FAIL before anything is extracted

Starter extension points

I edited each generated starter the way its README describes, using the README snippet verbatim, and ran it behind the same gateway. This was a manual run, not part of the script. Python and Rust gave the same results.

Request Result
Body note: prototype-secret inside Upstream receives note: [REDACTED] inside and the added header. OpenShell logs transformed:true.
Header x-omm-probe: deny HTTP 403 middleware_denied with reason_code: omm_probe_denied. The upstream is not contacted.
4,194,304-byte body ending in the marker Arrives as 4,194,298 bytes ending in [REDACTED], so a body at the 4 MiB platform maximum crosses gRPC in both directions.
4,194,305-byte body Arrives unchanged. OpenShell does not offer whole-body inspection above the limit.

omm update

Run on a project created by the published omm 0.0.1 at v0.0.86.

Scenario Result
Update to v0.0.90 Updated; its 5 tests pass
Update to v0.1.9 with default validation Refused, because the old starter code does not fit the new contract. The project is byte-identical afterwards.
Update to v0.1.9 with --check-command Updated. proto/extension.proto is added. Only the manifest, proto, and bindings change. A user file in proto/ keeps its inode.
Then update to v0.0.116 proto/extension.proto is removed; the user file stays
Project has its own, different proto/extension.proto Refused with a message to move it. The project is byte-identical.
Project has an identical copy of upstream's extension.proto Adopted

Other checks

  • Project checks from the README: ruff format --check, ruff check, ty check, pytest (118 passed, 96.16% coverage; main has 95 tests at 95.88%), and uv build. The tests also pass on Python 3.10.
  • The built wheel, installed with uvx, creates a Python starter with --openshell-version latest, creates a Rust starter, and runs omm update.
  • A generated Python starter passes its tests on Python 3.11. Starters named a, request.audit_log-v2, and partner-api-content-guard-v2 pass their checks in both languages.
  • omm create for v0.1.8, v0.1.0, v0.0.116, and v0.0.86 reports the new minimum-release error and leaves nothing on disk.
  • python3 scripts/update_license_headers.py --check passes.
  • With the deprecated unary RPC deleted from the contract, as OpenShell has announced for 0.2.0, the Rust starter still builds and passes its tests. Before the switch to default stubs it failed to compile.
  • An earlier single-agent review led to the per-file update publication above and to checksum enforcement in the script.
  • A three-reviewer panel then reviewed bd04b4e: Claude Opus 5.5, Claude Fable 5.2, and GPT-6.1 Sol, each at high effort. Fable's review of the generator's file safety was clean. Three findings were accepted and fixed in 6c7b6e0: the script's cleanup could abort under set -e and leave its gateway running; the Rust starter hand-wrote stubs for unused RPCs; and the generated READMEs did not list the imported protocol files as generator-owned. The live run, the stable-Rust run, and the Rust extension-point run above were repeated on 6c7b6e0.
  • omm: make generated Python packages importable for custom and reserved names #105 applies cleanly on top of this branch, and the 127 combined tests pass.

Not verified, and known limits

  • macOS and aarch64 were not run. The new no-replace move uses renameatx_np with RENAME_EXCL on macOS, which is untested. The script supports Linux only.
  • Only the Docker compute driver was exercised, with a plaintext registration (allow_insecure_transport). TLS and token-authenticated registrations were not tested; the starters remain unauthenticated development servers.
  • The starters do not implement streaming (DUPLEX) inspection. The generated READMEs say so.
  • The documentation site build was not run, because nothing under docs/ changed.
  • Not changed here: uv 0.13 warns that the Python template's uv_build>=0.11.8,<0.12.0 pin excludes the running uv. Builds still succeed.

Reviewed with sol-loop: 2 rounds with gpt-6.1-sol on high. Sol verdict: approved.

🤖 Generated with Claude Code

omm create failed for every OpenShell release since v0.1.0 because the
supervisor middleware proto imports extension.proto, which omm did not
download. The starter templates also still implemented the v0.0.86
contract.

Generator:
- Download the OpenShell protos that the middleware proto imports, record
  them in the manifest, and compile them into the Python bindings.
- Publish each generator-owned proto file on update by exchange, add, or
  removal with rollback, and refuse to overwrite an unrecorded file that
  differs from the imported one.
- Require the HTTP hooks contract (OpenShell v0.1.9 or newer) in
  omm create and report older releases before generating anything.

Templates:
- Negotiate extension protocol metadata in Describe.
- Implement HttpHooks.EvaluateHttpRequestHook with preflight and
  whole-body extension points in the Python and Rust starters.

Verification:
- Add scripts/verify-openshell-release.sh, which generates both starters
  and sends sandbox traffic through them behind a real OpenShell gateway.

Signed-off-by: Johnny Greco <jogreco@nvidia.com>
- Rust starter: build with tonic's generated default stubs and delete the
  hand-written "unimplemented" methods and stream types. A contract that
  adds or removes an RPC the starter does not implement, such as the
  removal of EvaluateHttpRequest announced for OpenShell 0.2.0, no longer
  breaks generated projects.
- Verification script: turn errexit off inside the cleanup handler so a
  failing cleanup command cannot skip stopping the gateway and services
  or replace the exit status.
- Generated READMEs: list the imported protocol files as part of the
  downloaded contract that the manifest records.

Signed-off-by: Johnny Greco <jogreco@nvidia.com>
@johnnygreco
johnnygreco merged commit 60be7c3 into main Nov 19, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant