feat(proxy): context-aware policy primitives (#13)

[olivrg]

Description

Adds three context-aware policy primitives for hook-based (host-enforced) adapters, building on the #12 sideband governance API. Third step of the OpenClaw adapter runway (#12 → #13 → #16 → #11).

• match.metadata.* — rules can match on adapter-supplied context (channel_id, sender_id, sender_name, conversation_id) plus a virtual agent_id key (read from the request column). Bare-string = eq, or an operator object (eq/neq/contains/regex, regex through the existing ReDoS analyzer). Threaded through the shared decision pipeline; inert on the MCP path by construction (no metadata there). Reserved agent_id inside metadata is rejected as a service-layer invariant (400 reserved_metadata_key).
• scope: by: sender_id — rate/spend limits keyed per adapter sender, backed by a GovernanceService reservation registry that caps distinct sender keys (fail-closed, sender:*-scoped only, default 50k) so caller-minted sender ids cannot starve the shared MCP-path limiter. Rejected at config when sdk.enabled is false; falls back to tool: with a warning on the MCP path.
• deny_install — install-time policy (policies.install) evaluated by POST /install-scan. Blocked installs persist policy_decision: deny + block_reason: install_denied and render as a deny in the dashboard.

MCP-path behavior is unchanged (the full existing proxy suite passes); docs (policies.md, adapter-api.md, audit.md) updated alongside the code.

Closes #13

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactor (no functional changes)
• Documentation
• CI / build / tooling

Packages Affected

• packages/proxy
• packages/dashboard
• packages/python-sdk
• Root config / monorepo tooling
• docs/
• examples/

Checklist

• I have read CONTRIBUTING.md
• My code follows the existing style (ESLint + Prettier pass)
• TypeScript strict mode — no any types or @ts-ignore without justification
• I have added or updated tests for my changes
• All CI checks pass (pnpm secrets:scan, pnpm docs:check:ci, pnpm audit --audit-level=high, pnpm build, pnpm lint, pnpm format:check, pnpm typecheck, pnpm test)
• I have updated documentation if this changes user-facing behavior
• Commit messages follow Conventional Commits (e.g. feat:, fix:, docs:)

How to Test

1. match.metadata — add a rule match: { metadata: { channel_id: "C1" } }, action: deny, enable the SDK sideband (sdk.enabled: true), and POST /evaluate with metadata: { channel_id: "C1" } → decision: deny; with channel_id: "C2" or no metadata → allow. Confirm the same rule never fires on the MCP path.
2. sender_id limits — a rate_limit rule with limits: { key: sender_id, … }: two /evaluate→/audit loops for the same sender_id consume one bucket; a different sender is independent. Set sdk.enabled: false and confirm helio validate rejects key: sender_id.
3. deny_install — add policies.install.rules with a deny_install rule (match: { name: "evil-*", source: npm }), POST /install-scan a matching package → decision: deny, and confirm the audit row shows record_kind: install_scan + block_reason: install_denied.
4. Reserved key — POST /evaluate with metadata: { agent_id: "x" } → 400 reserved_metadata_key.
5. pnpm --filter @gethelio/proxy test (1565) and pnpm --filter @gethelio/dashboard test (281) — full suites pass.

Additional Context