feat(agent): gate post-secret assertion pixels on engine proof

Closed
BH
20d ago
+397-31

What and why

  • Add an assertion-only screenshotPolicy through the built-in judge and shared pixel-policy check. Defaults and session taint remain unchanged. The option requires vision: 'only' at compile time and runtime.
  • Extend the existing engine SPI with optional capture-bound redaction evidence. Every capture, including retries, gets a fresh challenge. Complete full-frame proof and secure-field masking are both required.
  • This is a contract proposal. Neither shipped engine provides complete full-frame redaction, so this does not yet unblock post-secret visual assertions. No redaction sidecar or custom-executor bypass is added.
  • Preserve existing boundaries: post-secret semantic-capture failures cannot fall back to pixels. Report screenshots remain separate artifacts with secure-field-only masking, not full-frame attestation; screenshot: false disables the assertion artifact only.
await agent.assert('the authenticated screen is visible', {
  vision: 'only',
  screenshotPolicy: 'redacted-after-secrets',
});

Issue

Refs #1383. Engine-side full-frame redaction still needs maintainer design review. Action evidence remains separate in #1384.

Workflow

flowchart LR
  A[Built-in assertion] --> B{Explicit policy?}
  B -- no --> C[Existing pixel policy]
  B -- yes --> D[Fresh capture challenge]
  D --> E{Semantic capture and complete matching proof and masking?}
  E -- no --> F[Fail before model call]
  E -- yes --> G[Existing visual judgment]
  G --> H[Session remains tainted]

Verified

Ran it locally: yes

  • Built CLI with a synthetic engine returning constant secret-free pixels and a scripted model. This verifies the permission path, not a seeing model, real redactor, or device.
Built CLI scenariomainthis branch
New option with missing proofINVALID_ARGUMENT, no judge callPOLICY_DENIED, zero judge calls
New option with complete matching proofINVALID_ARGUMENT, no judge callPasses, visionInput: true, one scripted judge call
Next assertion without the opt-inExisting secret-pixel restrictionStill PIXEL_TAINTED
  • Rechecked retry behavior locally on 72d84b157e74 with the built CLI:
Fresh retry proof: 1 passed, 1 model call
Stale retry proof: POLICY_DENIED / PIXEL_TAINTED, no model call
Review regressionPrevious PR headThis head
Policy with vision: true, false, or omittedAll three type-checkAll three rejected by compile-time assertions
  • Current-head local checks: 14 post-secret integration cases, 33 combined policy/vision cases, 3,038 unit tests passed with one skipped, workspace typechecking, docs validation, lint, and contract/package checks passed. No report/session wire format or cache-key changes.
  • On head 72d84b157e74, spec CI passed static checks, all Node test jobs, and install smoke tests. iOS and Android deterministic jobs in mobile CI remain running. Docs CI and the deterministic web benchmark passed. Agentic web benchmark execution is skipped on this fork PR.
  • Cubic re-review completed on 72d84b157e74: zero issues across the 10 changed files. All 10 original review threads have replies and are resolved.
  • No local full-suite, live-provider, mobile-device, benchmark, rendered-docs, or independent local-review claim. Maintainer agreement on the attestation contract remains required. Existing patch changesets cover e2e, @e2e-dev/web, and @e2e-dev/mobile.