RFC: Agent-First Event Filtering

Summary

AgentInbox should move from today's flat matchRules map to an agent-first filtering model with:

• explicit metadata and payload namespaces
• a stable source schema surface for normalized fields
• an optional JS-like filter expression evaluated in a sandbox
• a small helper-function set inspired by GitHub Actions expressions and workflow filters

The goal is not human-friendly syntax. The goal is to let agents write correct filters without memorizing a project- specific DSL.

Problem

Current Subscription.matchRules is too weak and too ambiguous.

Today it has these limitations:

• it flattens normalized metadata and source-native payload into one map
• it only supports simple equality, array membership, and contains:
• it does not support and / or / not
• it does not support nested payload access
• it does not expose a clear schema contract for agents

This creates two problems:

1. agents cannot easily express common filtering needs such as:
   • only completed workflow runs
   • completed failures only
   • filter out self-authored GitHub comments
   • match nested payload paths such as payload.sender.login
2. agents cannot easily tell whether a field is:
   • a stable AgentInbox normalized field
   • or a source-native payload field

Goals

• make event filtering explicit about metadata vs payload
• let agents use a familiar JS-like boolean expression syntax
• keep normalized metadata as the stable filtering contract
• still allow source-native filtering for GitHub and other familiar sources
• provide a small built-in helper set that covers common filtering cases
• make future source schema introspection straightforward

Non-Goals

• do not support arbitrary JavaScript execution
• do not expose filesystem, network, time, randomness, or process state
• do not preserve backward compatibility with the current flat matchRules
• do not build a general workflow engine

Event Model

Every normalized event should continue to have:

• eventVariant
• metadata
• payload
• sourceType
• sourceKey

Filtering should treat these as separate namespaces.

metadata

metadata is the stable, normalized, source-type-specific contract.

Examples for github_repo_ci:

• metadata.status
• metadata.conclusion
• metadata.name
• metadata.headBranch
• metadata.actor

Rules:

• metadata fields are what AgentInbox documents via source schema
• metadata should be the recommended default filtering surface
• source adapters should favor adding stable, high-value fields here

payload

payload is the source-native event body.

Examples:

• payload.event
• payload.sender.login
• payload.head_commit.message

Rules:

• payload is allowed in filters
• payload is not promised to be cross-source stable
• payload is useful when the agent already understands the provider's event shape, such as GitHub

Proposed Subscription Filter Shape

Replace the current flat matchRules map with:

{
  "metadata": {
    "status": "completed",
    "conclusion": "failure"
  },
  "payload": {
    "event": "pull_request"
  },
  "expr": "metadata.status == 'completed' && metadata.conclusion == 'failure'"
}

Interpretation:

• metadata and payload blocks are simple exact-match shortcuts
• expr is optional and evaluated after the shortcut blocks match
• if expr is absent, only the shortcut blocks are used

This keeps the simple path simple while giving agents an escape hatch for more complex logic.

Expression Language

Use a JS-like boolean expression syntax implemented via JEXL.

Why JEXL:

• agents are already good at writing JS-like boolean expressions
• dotted path access is natural
• it is more natural for agents than a JSON DSL such as JsonLogic
• it can be sandboxed more safely than arbitrary JS

Expression Context

The filter expression should only receive these variables:

• metadata
• payload
• eventVariant
• sourceType
• sourceKey

Example:

metadata.status == "completed" &&
metadata.conclusion == "failure" &&
payload.sender.login != "jolestar"

Allowed Operators

Allow the normal boolean and comparison operators supported by JEXL:

• ==
• !=
• >
• >=
• <
• <=
• &&
• ||
• !

Also allow dotted path access such as:

• metadata.status
• payload.sender.login
• payload.head_commit.message

Helper Functions

The helper-function set should be intentionally small.

The baseline should be inspired by GitHub Actions expression helpers and GitHub workflow filter patterns.

Functions To Support

• contains(search, item)
• startsWith(searchString, searchValue)
• endsWith(searchString, searchValue)
• format(template, ...)
• join(array, separator)
• matches(value, pattern)
• glob(value, pattern)
• exists(value)

Rationale

GitHub Actions already established a familiar mental model for:

• contains
• startsWith
• endsWith
• format
• join

AgentInbox should follow that familiarity where possible.

Two additions are worth making:

• matches
  • regex-based matching for advanced filtering
• glob
  • branch/path-like matching inspired by GitHub workflow filters

exists is useful for sparse source-native payloads.

Example Filters

Only completed GitHub CI failures:

metadata.status == "completed" &&
metadata.conclusion == "failure"

Filter out self-authored GitHub comments:

payload.sender.login != "jolestar"

Only CI workflows on release branches:

metadata.status == "completed" &&
glob(metadata.headBranch, "release/*")

Match workflow names using a GitHub-style helper:

contains(["CI", "Copilot Code Review"], metadata.name) &&
metadata.status == "completed"

Match nested payload content:

contains(payload.head_commit.message, "[notify-agent]")

Evaluation Rules

Filter evaluation should run in this order:

1. exact match against metadata block, if present
2. exact match against payload block, if present
3. evaluate expr, if present

All present parts must pass for the event to match.

This keeps the common case cheap and deterministic.

Source Schema

This RFC assumes a future source schema command such as:

agentinbox source schema github_repo_ci

Expected output should be split explicitly:

• metadataFields
• payloadExamples
• eventVariantExamples
• configFields

This is important because the filter model only stays clear if agents can ask:

• what stable metadata fields exist?
• what does the source-native payload look like?

Security And Runtime Constraints

The expression engine must remain sandboxed.

Rules:

• no arbitrary JS eval
• no process access
• no filesystem access
• no network access
• no clocks or random helpers
• bounded execution time
• bounded memory use

The context should be pure event data and helper functions only.

Migration

Compatibility is not a goal for this RFC.

Migration plan:

1. replace flat matchRules with a structured filter object
2. implement namespaced shortcut blocks:
   • metadata
   • payload
3. add expr powered by JEXL
4. add source schema
5. update source adapters to make metadata contracts explicit

Open Questions

• should expr be named expr, filter, or when?
• should metadata and payload shortcut blocks support nested operator objects such as {"status": {"in": ["queued", "in_progress"]}}, or should advanced logic live entirely in expr?
• should helper functions be global or namespaced?
• should glob follow GitHub's exact wildcard semantics, or a smaller subset?

Recommendation

Adopt the following as the next filtering model:

• explicit metadata and payload filter namespaces
• JEXL as the expression engine
• a small helper set:
  • contains
  • startsWith
  • endsWith
  • format
  • join
  • matches
  • glob
  • exists

This gives agents a filtering language they are already good at producing, while keeping AgentInbox's normalized metadata model explicit and stable.