maka/docs/computer-use-host-events-contract.md

Computer Use Host Events Contract

This layer connects only events with a typed, attributable source.

Connected producers

• Typed dispatch outcomes:
  • user_intervened -> re-observe
  • screen_locked -> locked
  • blocked_url -> terminal URL block
  • outcome_unknown, service unavailable, or service mismatch -> re-observe
• Executor service release:
  • clears executor-local observations and keyboard ownership
  • advances the corresponding Runtime session to re-observe
• Turn/session terminal events:
  • synchronously clear Runtime, executor, and overlay ownership

Deliberate gaps

• Maka does not infer physical user input from AX or DOM content changes.
• Maka does not claim a global physical-input producer until it has a reliable, attributable macOS event source.
• Maka does not invoke Codex's signed turn-ended helper. That helper uses an Apple Event lifecycle specific to the Codex native service, and helper process exit is not proof that service cleanup completed.
• Runtime URL, lock, and intervention states require typed driver outcomes; raw error-message matching is not an accepted producer.
• The current driver exposes no trustworthy intervention debounce deadline, so a typed intervention advances directly to re-observe. The two-stage debounce state remains reserved for a future attributable deadline producer.
• Maka currently binds targets by PID/window/content/page identity. The V10 reverse-engineered boundary is stronger: canonical app path plus the current live process instance. Maka does not claim that boundary until the executor or a native host API can provide an atomic, high-precision process identity.

Verification

The cross-layer deterministic harness covers:

• bound target propagation;
• observation-bound presentation and dispatch;
• fresh post-action observation;
• duplicate and stale rejection;
• typed target-change cancellation;
• unknown outcome requiring re-observation;
• explicit session cleanup;
• private UI content omission from persisted tool text while current-turn model projection retains the UI evidence needed for action.

Target/decoy execution, real process restart, persistence-level privacy, Desktop terminal lifecycle, real macOS event production, and real-window cumulative Electron verification remain separate release gates.