#+TITLE: org-agent Communication Protocol (OACP)
#+AUTHOR: Agent
#+DATE: 2026-03-22
#+ID: org-agent-protocol
#+STARTUP: content

* Core Mandates
The OACP and the `org-agent` project MUST adhere to these foundational mandates:
- **Mandate 1: Strict Homoiconic Memory.** All documentation, planning, and system logic MUST be authored in Org-mode (.org) and Common Lisp. Markdown (.md) and JSON are strictly prohibited for internal use.
- **Mandate 2: Minimalist Microkernel.** The core daemon MUST remain minimalist, handling only the cognitive loop, the persistent Object-Store, and the communication protocol. All domain-specific features and LLM provider logic MUST be implemented as hot-reloadable **Skills** living in the user's Memex.

* Overview

OACP (org-agent Communication Protocol) defines the "nervous system" of the Neurosymbolic Lisp Machine. It facilitates bidirectional, asynchronous communication between the **Common Lisp Core** (The Soul/Daemon) and the **Emacs Interface** (The Actuator/Terminal).

The protocol is designed to be:
- **Homoiconic:** Messages are native Lisp S-expressions (plists).
- **Asynchronous:** Neither side should block waiting for the other.
- **Extensible:** New sensors and actuators can be added by defining new plist keys.

* Framing & Transport

- **Transport:** TCP Socket (default port: 9105).
- **Framing:** Each message is prefixed by a 6-character hexadecimal length string (e.g., `00002a` for a 42-byte message), followed by the S-expression string encoded in UTF-8.

* Message Structure

A standard message is a flat property list (plist):

#+begin_src lisp
(:type TYPE :id ID :payload PAYLOAD)
#+end_src

- **:type:** One of `:EVENT`, `:REQUEST`, `:RESPONSE`, or `:LOG`.
- **:id:** A unique integer or string for correlation (mandatory for `:REQUEST` and `:RESPONSE`).
- **:payload:** A nested plist containing the specific data or command.

* Perception (Emacs -> Core)

Emacs acts as the sensor array, pushing events to the Core daemon.

** :BUFFER-MODIFIED
Sent when an Org buffer is changed or saved.
#+begin_src lisp
(:type :EVENT :payload (:sensor :buffer-update :file "/home/amr/org/todo.org" :state :saved))
#+end_src

** :USER-INPUT
Sent when the user explicitly triggers an agent action (e.g., `M-x org-agent-ask`).
#+begin_src lisp
(:type :EVENT :payload (:sensor :user-prompt :text "Refactor this subtree" :context :current-subtree))
#+end_src

** :CURSOR-MOVED
Sent when the agent needs to track the user's focus.
#+begin_src lisp
(:type :EVENT :payload (:sensor :focus :buffer "init.el" :line 42 :column 0))
#+end_src

* Action (Core -> Emacs)

The Core daemon sends requests to Emacs to perform physical actions in the environment.

** :EXECUTE-ELISP
The primary "actuator."
#+begin_src lisp
(:type :REQUEST :id 101 :payload (:action :eval :code "(org-todo \"NEXT\")"))
#+end_src

** :UI-NOTIFY
Display info to the user without interrupting focus.
#+begin_src lisp
(:type :REQUEST :id 102 :payload (:action :message :text "I have identified a contradiction in your GTD.org" :level :warning))
#+end_src

** :PROVIDE-COMPLETION
Provide LLM-driven completions for the current point.
#+begin_src lisp
(:type :REQUEST :id 103 :payload (:action :complete :prefix "defun" :suggestions ("defun-agent" "defun-percieve")))
#+end_src

** :ORG-DELIVERY
Enqueue external messages.
#+begin_src lisp
(:type :REQUEST :target :delivery :payload (:channel :signal :to "+1..." :text "Hello"))
#+end_src

** :PROJECT-SCAFFOLD
Create new project folders and headings.
#+begin_src lisp
(:type :REQUEST :target :foundry :payload (:action :scaffold :name "Project-X" :type "Lisp"))
#+end_src

** :SYSTEM-SELF-EDIT
Kernel-level self-modification.
#+begin_src lisp
(:type :REQUEST :target :system :payload (:action :create-skill :filename "skill-x.org" :content "..."))
#+end_src

* Metadata & Handshake

** :HELLO
Sent by both sides upon connection.
#+begin_src lisp
(:type :EVENT :payload (:action :handshake :version "0.1.0" :capabilities (:auth :swank :org-ast)))
#+end_src

* Cognitive Loop Internal API (Foundry Standard)

To ensure neurosymbolic sovereignty, the Core Daemon must strictly separate stages.

** 1. Perceive
- **Signature:** `(perceive raw-stimulus) -> context-plist`
- **Responsibility:** Protocol decoding, Object-Store synchronization, context augmentation.

** 2. Think (System 1)
- **Signature:** `(think context-plist) -> proposed-action-plist`
- **Responsibility:** Neural pattern matching, associative retrieval, unverified proposal generation.

** 3. Decide (System 2)
- **Signature:** `(decide proposed-action context) -> approved-action-plist`
- **Responsibility:** Symbolic verification, safety gating, deterministic rule application (e.g., GTD logic).

** 4. Act (Dispatch)
- **Signature:** `(act stream approved-action)` / `(dispatch-action approved-action)`
- **Responsibility:** Actuator lookup and transmission. Targets: `:emacs`, `:delivery`, `:system`, `:shell`.

** 5. Context API (System 1 Peripheral Vision)
- **(context-list-all-skills):** Introspect the brain hierarchy.
- **(context-get-skill-source name):** Read the logic graph.
- **(context-resolve-path path):** Environment-relative path expansion.
- **(context-get-system-logs limit):** Perception of kernel failures.

* Success Metrics
- Latency between `:EVENT` and `:RESPONSE` < 100ms for UI actions.
- 100% fidelity in Org AST preservation across the bridge.
- Zero UI blocking in Emacs during heavy CL reasoning loops.