Proactive Layer — Design#

This adds a layer of "proactivity" to OpenProgram: while the agent is working, the framework watches on its own and steps in when it should — blocking dangerous commands, reminding you of tests that need to be added, noticing when the model is stuck. The user doesn't have to say a word, and the framework still acts.

The core of this layer is event-driven: every thing that happens while the agent works (user sends a message, model replies, calls a tool, a tool fails, a file gets changed) is recorded as an "event"; your proactive rules aren't welded to some fixed location, but instead "subscribe" to these events — when an event fires, they're woken up, make a judgment, and decide whether to step in.

This layer splits into two parts: event foundation + proactivity application#

• Event foundation (the bedrock, used by the whole framework): one unified event stream that anyone can subscribe to. proactive is just its first consumer; webui and other future features can use it too.
• Proactivity application (built on the foundation): rules (Policy) subscribe to the event stream and step in when they should.

The two parts are decoupled. You can build just the foundation and hold off on the rules.

How to read#

Read the event foundation first (this is exactly what you've been validating recently — whether the system actually supports "do something at some moment"):

0. event-reference.html — the official API Reference: every event type (26 of them, across the three categories A / B / ws.frame) listed one by one, each with a payload field table, trigger timing, and source file:line; the full API and all three usages (observe / intercept / ask). Searchable and expandable. Double-click to open in a browser. Check it first when looking up an event.
1. event-layer.md — the unified Event model + where this layer sits in the framework + the architecture diagram. What an event looks like, the two major classes of event sources (agent at work / system state), where the bus lives, and who it interacts with. Visual version: event-layer.html (a real SVG architecture diagram + event-flow animation, double-click to open in a browser); the md is the text source of the same content.
2. framework-evolution.md — how signals are routed across the framework. Why routing through webui leaves gaps, what the bus as the hub gives each role, what each subsystem contributes, and what the design leaves untouched. Visual version: framework-evolution.html.

Then read the proactivity application (the proactive layer built on top of the foundation):

2. overview.md — walk through one scenario end to end (the model wants to run rm -rf, and how the framework blocks it); concepts like rules, ways of stepping in, and state are explained in place within the story.
3. events-and-state.md — how state is "accumulated" (folded) out of events; this is the principle that lets rules "remember the past".

Want to get hands-on or discuss the details:

A one-line answer to a few questions you might ask#

Implementation status#

The event foundation is in place: the bus is enabled, both classes of source emit into it, tool.before carries the synchronous interception point, and webui consumes the bus as an ordinary subscriber. The proactive rule layer described in execution-model.md and policies-mvp.md is the part not yet built. The event log is always on: send a message, then read ~/.openprogram/sessions/<sid>/events.jsonl (or ~/.openprogram/logs/events.jsonl for events outside a session).