feat: agent-driven policy management MVP

[zredlined]

Summary

MVP of agent-driven policy management — the loop where an in-sandbox agent
hits a policy block, drafts a narrow rule, submits it via policy.local,
and the developer approves out-of-band. Implements the vertical slice
described in RFC 0001 and
tracked under #1062, with the build plan in
architecture/plans/agent-driven-policy-management-v1.md.

The full loop demoed end-to-end with Codex inside an OpenShell sandbox
writes a markdown file to GitHub via a proposal-and-approval round-trip
that takes about two minutes total.

Related Issue

Refs #1062.

Demo output

Real run from a local dev gateway against a scratch GitHub repo. The whole
loop is bash examples/agent-driven-policy-management/demo.sh with no
arguments — defaults resolve from gh and ~/.codex/auth.json.

==> Preflight

  gateway:  connected · 0.0.37-dev.66+g91014bce
  github:   <owner>/openshell-policy-demo @ main (ab75c15)
  providers created (codex, github) — credentials injected as env vars only

==> Run summary

  repo:     <owner>/openshell-policy-demo
  branch:   main
  target:   openshell-policy-advisor-demo/<run-id>.md
  sandbox:  policy-demo-<run-id>

==> Launching sandbox; agent will hit a policy block and draft a proposal

  initial policy:  read-only access to api.github.com (no PUT)
  agent task:      PUT /repos/<owner>/openshell-policy-demo/contents/...
  live log:        /tmp/openshell-policy-demo.XXXXXX/agent.log

==> Waiting for the agent to draft a policy proposal

  Inside the sandbox right now:

    [1] agent: curl -X PUT https://api.github.com/repos/<owner>/.../contents/...
    [2] L7 proxy denies the write and returns a structured 403 the
        agent can parse and act on:
        {
          "error":      "policy_denied",
          "layer":      "l7",
          "method":     "PUT",
          "path":       "/repos/<owner>/.../contents/<run-id>.md",
          "rule_missing": { "type": "rest_allow", "host": "api.github.com", "port": 443, "method": "PUT", ... },
          "next_steps": [
            { "action": "read_skill",      "path": "/etc/openshell/skills/policy_advisor.md" },
            { "action": "submit_proposal", "url":  "http://policy.local/v1/proposals" }
          ]
        }
    [3] agent reads the skill, drafts a narrow addRule for exactly that path
    [4] agent POSTs the proposal to http://policy.local/v1/proposals
    [5] supervisor forwards it to the gateway as a pending draft

  Polling for the pending draft...

  proposal received:
  Binary: /usr/bin/curl
  Rationale: Allow /usr/bin/curl to write one GitHub Contents API file for run <run-id> in <owner>/openshell-policy-demo only.
  Endpoints: api.github.com:443 [L7 rest, allow PUT /repos/<owner>/openshell-policy-demo/contents/openshell-policy-advisor-demo/<run-id>.md]

==> Approving and waiting for the agent to retry

  OK 1 chunk(s) approved, 0 skipped. Policy version: 2
  agent retried after policy hot-reload — write succeeded

==> Verifying GitHub write

  file: openshell-policy-advisor-demo/<run-id>.md
  url:  https://github.com/<owner>/openshell-policy-demo/blob/main/...

==> Policy decision trace (OCSF)

  [t+0]  HTTP:PUT [MED] DENIED  PUT http://api.github.com:443/repos/.../...md [policy:github_api_readonly engine:l7] [reason:L7_REQUEST deny PUT ...]
  [t+26] CONFIG:LOADED [INFO] Policy reloaded successfully [policy_hash:...]
  [t+50] HTTP:PUT [INFO] ALLOWED PUT http://api.github.com:443/repos/.../...md [policy:github_api_readonly engine:l7]

✓ Demo complete.

Two things worth calling out from this output:

1. The Endpoints: line shows the actual L7 grant — [L7 rest, allow PUT /repos/.../...md]. Codex submits a method/path-scoped REST rule, not a broad L4 allow. Before this PR, openshell rule get rendered only host:port and dropped protocol, access, and the rules array, so a developer at approval time couldn't tell L4 from L7. The CLI rendering fix surfaces what the agent already submits.
2. The structured 403 body is the contract. It carries layer, method, path, rule_missing, and next_steps — enough for the agent to recover without prompt scaffolding telling it which file to read. Reading the skill is one of the next_steps the response itself names.

Changes

feat(sandbox): wire policy.local denials to OCSF JSONL log

• GET /v1/denials?last=N on the sandbox-local API now reads the OCSF
  JSONL log at /var/log/openshell-ocsf.YYYY-MM-DD.log, filters to network
  and L7 denials (action_id=2, class_uid 4001/4002), and returns a
  compact summary newest-first. Default limit 10, capped at 100. Runs in
  spawn_blocking so file I/O does not stall the policy.local handler.
• POST /v1/proposals now uses the typed grpc_client wrapper instead of
  raw_client. Wrapper return type extended to the response struct so
  accepted/rejected counts surface uniformly.
• Dropped the add_rule snake_case alias in proposal JSON; canonical
  form is addRule, matching PolicyMergeOperation convention used
  elsewhere in the codebase.
• skills/policy_advisor.md updated to document the now-real
  /v1/denials?last=10 endpoint and use addRule consistently.

feat(cli): show L7 protocol/method/path in rule get output

format_endpoint() previously rendered only host:port, dropping
protocol, access, and the L7 rules array. That made
openshell rule get text output unable to distinguish a broad L4 grant
from a method/path-scoped L7 REST rule — exactly the distinction a
developer needs at approval time.

New rendering tags each endpoint with its enforcement layer and surfaces
allow/deny rules:

bare L4:           api.example:443 [L4]
L7 read-only:      api.example:443 [L7 rest, access=read-only]
L7 method/path:    api.example:443 [L7 rest, allow PUT /v1/foo/bar]

Pure display change: no proto, gateway, or behavior changes. Unit test
covers all three cases with synthetic fixtures.

refactor(examples): rewrite policy demo as Codex-default loop

Re-shaped examples/agent-driven-policy-management/ as a single, clean
end-to-end demonstration with smart defaults — bash demo.sh works after
gh auth login and codex login, with no .env ceremony or required
arguments. Defaults resolve from gh (owner via gh api user, repo
defaults to openshell-policy-demo, token from gh auth token).

Demo output narrates the loop for a developer reading along: structured
deny body the agent receives, the agent's drafted proposal (now showing
the L7 method/path), the policy hot-reload, and the OCSF trace at the end
filtered to the three story-relevant events.

Moved the deterministic no-LLM regression harness out of examples/ into
e2e/policy-advisor/ — it was a parallel demo, not an example. Same loop
without the LLM, useful for iterating on the proxy and policy.local API.

The README documents the trust model honestly: structured rule is the
contract, agent rationale is a hint, prover validation badge in progress
per RFC 0001 Phase 3.

Testing

• cargo test -p openshell-sandbox --lib (650 tests, all pass; 13 in
  policy_local::tests)
• cargo test -p openshell-cli format_endpoint (renderer unit test
  covers L4, L7 read-only, L7 method/path)
• cargo clippy -p openshell-sandbox --lib --tests -- -D warnings (clean)
• shellcheck clean on demo.sh, sandbox-agent.sh,
  e2e/policy-advisor/test.sh, e2e/policy-advisor/sandbox-runner.sh
• Manual end-to-end: bash examples/agent-driven-policy-management/demo.sh
  against a local gateway with Codex auth and a scratch GitHub repo.
  Confirmed Codex submits a method/path-scoped L7 REST rule (visible
  after the CLI rendering fix) and that hot-reload + retry works.

Update (review iteration, May 6)

After the initial draft and a quick sync with @johntmyers on the design,
two follow-up commits land on this branch:

1. docs(policy-advisor): refresh L7 deny note for structured 403 contract
   — architecture/policy-advisor.md line 47 was stale (still framed L7
   deny as future work under feat: LLM-powered PolicyAdvisor agent harness for intelligent policy recommendations #205). Updated to reflect the structured 403
   body that this PR delivers against feat(policy): add agent-readable L7 deny body #1090; LLM enrichment remains the
   only piece left for feat: LLM-powered PolicyAdvisor agent harness for intelligent policy recommendations #205.

2. feat(sandbox): switch /v1/denials to shorthand log pass-through — the
   sandbox-local /v1/denials endpoint previously parsed
   /var/log/openshell-ocsf.*.log (OCSF JSONL), which is opt-in via
   ocsf_json_enabled. By default the endpoint returned an empty list with
   a "log not enabled" hint, breaking the inspect_recent_denials step in
   the structured 403's next_steps array out of the box.

   Two ways to fix this: flip ocsf_json_enabled=true by default, or read
   the always-on shorthand log instead. The first opens a defaults /
   compliance discussion (every sandbox would persist a daily-rotated
   audit trail on upgrade). The second is what the team picked: read the
   shorthand log and pass raw lines through to the agent — same content,
   no defaults change, easier to extend (adding fields to the shorthand
   renderer is a single-file change here, no schema rev).

   Verified end-to-end against a fresh sandbox: /v1/denials now returns
   an array of raw shorthand strings, newest-first, with log_available: true out of the box.

   The principal-engineer review also caught two correctness issues that
   are addressed in the same commit:

   • UTF-8 boundary: byte-naive &line[..MAX] would panic on
     multi-byte sequences. Now uses an is_char_boundary walk-down via
     truncate_at_char_boundary, with a multi-byte test.
   • Query-string leak (consumer-side fix): the FORWARD deny path in
     proxy.rs populates OcsfUrl::new(...) and .message(...) with the
     raw request path including ?query=..., unlike the L7 path which
     uses redacted_target. To keep secrets out of /v1/denials while
     the upstream emit sites are tightened separately,
     redact_query_strings strips ?<query> to ?[redacted] from each
     surfaced line, before truncation so a cut cannot slice mid-secret.
     Hardening the upstream emit sites in proxy.rs so the on-disk
     shorthand log is itself clean is tracked as a follow-up — the
     consumer-side redaction is defense-in-depth.

Net result: the agent loop ergonomics are now live by default with no
sandbox setting changes, and the pre-existing FORWARD-path leak is gated
out of the new agent surface.

Checklist

• Follows Conventional Commits (feat(sandbox), feat(cli),
  refactor(examples))
• Commits signed off — happy to amend with --signoff if maintainers
  want; matched the existing branch style for now
• Architecture docs current — architecture/policy-advisor.md updated
  to reflect the structured 403 deny body delivered against feat(policy): add agent-readable L7 deny body #1090;
  RFC 0001 and the build plan describe the broader scope.
• Adds neither prescriptive prompt scaffolding nor per-host heuristics.
  The renderer surfaces what the agent submitted; if a future agent
  defaults to L4 against a known-REST host, that signal belongs in the
  gateway-side prover (Phase 3), not in the prompt.

Out of scope (deferred per the build plan)

• Multi-sandbox push inbox (TUI polling 2s for now)
• Slack / web inbox adapters
• Supervisor UDS API (sandbox-local HTTP at policy.local is the agent
  surface this PR ships)
• In-process prover optimization
• Org ceiling and trusted external auto-apply
• Per-binary auto-approve patterns

Side note

While testing this branch I noticed examples/multi-agent-notepad/demo.sh
regressed against main after #952 / #1028 changed --upload <dir>:<dir>
semantics. Filed as #1147 with a five-line suggested fix. Not in scope here.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[zredlined]

Rebased onto origin/main (now fe41d679) to resolve the conflict. Force-pushed; new head is 84f4e29f.

Three real conflicts during the replay:

1. Cargo.lock (lockfile-refresh commit, third in the series) — took main's lockfile and verified cargo check -p openshell-sandbox --lib still resolves cleanly against this branch's Cargo.toml.

2. crates/openshell-cli/src/run.rs (the L7-rule-rendering commit feat(cli): show L7 protocol/method/path in rule get output) — pure import-list collision in the test module's use super::{...}. Kept main's three new symbols (dockerfile_sources_supported_for_gateway, gateway_env_override_warning, resolve_from) and this branch's new format_endpoint. Verified all four exist as actual symbols in the file at this commit.

3. Semantic mismatch with feat(policy): add GraphQL L7 inspection #1083 (GraphQL L7 inspection) — main added new fields to L7Allow, L7DenyRule, and NetworkEndpoint, plus a sixth DenyResponseContext parameter to RestProvider::deny_with_redacted_target. Git didn't flag these as text conflicts; they showed up as compile errors after the rebase. Folded into one cleanup commit on top:

   • 84f4e29f chore(sandbox): align proto inits with main's L7 GraphQL additions
   • crates/openshell-sandbox/src/l7/relay.rs — two deny_with_redacted_target call sites (REST and GraphQL deny paths) now pass DenyResponseContext { host, port, binary } matching the pattern at line 581.
   • crates/openshell-sandbox/src/policy_local.rs — L7Allow, L7DenyRule, and NetworkEndpoint initializers populate the new GraphQL/path-scoping fields with empty defaults. Agent-authored proposals from policy.local target REST/SQL/L4 today; GraphQL operation matching is set on the gateway side or via direct YAML, so empty defaults are correct here.

Verified locally:

• cargo test -p openshell-sandbox --lib → 650 pass, 2 ignored
• cargo clippy -p openshell-sandbox --lib --tests -- -D warnings → clean
• Re-ran the e2e flow against a fresh sandbox: /v1/denials still returns raw shorthand strings newest-first; structured 403 deny body unchanged; proposal submit + approve + retry cycle still works end-to-end.

The two recent commits on top (676934e4 docs/architecture refresh and c8e5c6a9 shorthand pass-through with redaction + UTF-8 safety) are unchanged in content; just rebased SHAs.

[zredlined]

Rebased again — main moved another 20 commits forward and PR #1184 (architecture-doc reset) deleted architecture/policy-advisor.md, the file my prior docs(policy-advisor) commit edited. New head is f48f4c87.

Changes during this rebase:

• Dropped 676934e4 docs(policy-advisor): refresh L7 deny note for structured 403 contract — target file is gone from main. Same context already lives in RFC 0001 in this branch; no content lost.
• Resolved 1 conflict in crates/openshell-cli/src/run.rs — kept main's refactored CLI test imports while preserving the branch's format_endpoint L7 rendering helper and unit coverage.
• Verified: cargo test -p openshell-sandbox --lib (595 pass, 1 ignored), cargo clippy -p openshell-sandbox --lib --tests -- -D warnings (clean).

Ready for review.

[github-actions]

Label test:e2e applied, but pull-request/1151 is at {"messa while the PR head is 63b5288. A maintainer needs to comment /ok to test 63b528804a392edd0ddf2ab748b22fc8ec32baf1 to refresh the mirror. Once the mirror catches up, re-run Branch E2E Checks from the Actions tab.

[johntmyers]

/ok to test 63b5288