:PROPERTIES:
:ID:       4829cb25-efcb-4e0f-9285-7a045213d8b9
:END:
#+TITLE: SKILL: Chat Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :chat:conversational:ui:psf:

* Overview
The *Chat Agent* provides a dedicated conversational interface within Emacs (`*org-agent-chat*`). It enables fluid dialogue while maintaining strict persona alignment and contextual awareness.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define the interfaces for direct human-to-agent conversational interaction.

** 2. User Needs
- *Direct Interaction:* Specialized handler for `:chat-message` events.
- *Persona Alignment:* Consistency with the Identity Agent's definitions.
- *Contextual Awareness:* Reference to chat history for dialogue continuity.
- *Structural Output:* Responses formatted as valid Org-mode subtrees.

** 3. Success Criteria
*** TODO Chat Event Triggering
*** TODO Persona-Driven Response Generation
*** TODO Emacs Buffer Insertion Verification

* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

** 1. Architectural Intent
Interfaces for conversational event handling and UI integration. Source of truth is the dynamic chat buffer and the Identity skill.

** 2. Semantic Interfaces
#+begin_src lisp
(defun trigger-skill-chat (context)
  "Triggers on :sensor :chat-message.")

(defun verify-skill-chat (proposed-action context)
  "Ensures response is targeted to the correct Emacs buffer.")
#+end_src

* Phase D: Build (Implementation)

** Event Perception
#+begin_src lisp :tangle ../projects/org-skill-chat/src/chat-logic.lisp
(defun trigger-skill-chat (context)
  (let* ((payload (getf context :payload))
         (sensor (getf payload :sensor)))
    (eq sensor :chat-message)))
#+end_src

** Symbolic Verification
#+begin_src lisp :tangle ../projects/org-skill-chat/src/chat-logic.lisp
(defun verify-skill-chat (proposed-action context)
  (if (and (listp proposed-action)
           (or (and (member (getf proposed-action :type) '(:request :REQUEST))
                    (or (and (member (getf proposed-action :target) '(:emacs :EMACS))
                             (member (getf (getf proposed-action :payload) :action) '(:insert-at-end :INSERT-AT-END)))
                        (and (member (getf proposed-action :target) '(:shell :SHELL))
                             (getf (getf proposed-action :payload) :cmd))))
               (member (getf proposed-action :type) '(:response :RESPONSE :log :LOG))))
      proposed-action
      (let ((err-text (format nil "\n\n*System Error:* Chat agent returned invalid action: ~s" proposed-action)))
        `(:type :request :target :emacs :payload (:action :insert-at-end :buffer "*org-agent-chat*" :text ,err-text)))))
#+end_src

** Neural Response Generation
The Chat skill acts as the conversational UI. Because the ~org-agent~ kernel evaluates LLM output via ~read-from-string~ (expecting a valid s-expression) and the chat verifier strictly expects an Emacs ~:insert-at-end~ actuation, we must explicitly mandate that the LLM wraps its conversational output in a Common Lisp property list.

#+begin_src lisp :tangle ../projects/org-skill-chat/src/chat-logic.lisp
(defun neuro-skill-chat (context)
  "Generates a conversational response using the PSF Identity persona, 
mandating an s-expression return format."
  (let* ((payload (getf context :payload))
         (text (getf payload :text))
         (user (or (uiop:getenv "MEMEX_USER") "User"))
         (assistant (or (uiop:getenv "MEMEX_ASSISTANT") "Passepartout")))
    (ask-neuro text :system-prompt (format nil "IDENTITY: You are ~a, the sovereign assistant to ~a. 
MANDATE: Speak ONLY in Org-mode subtrees. No double asterisks.
INTERFACE: You are a pure actuator function. Your output MUST be exactly one Common Lisp property list.

STRICT RULES:
1. Do NOT output any conversational text.
2. DO NOT say 'Okay', 'I will do that', or 'I am inserting'.
3. DO NOT wrap the output in quotes or markdown blocks.
4. Your entire response must parse as a valid Common Lisp list.

EXAMPLE OF A BAD RESPONSE:
Okay, here is your answer:
(:type :request ...)

EXAMPLE OF A GOOD RESPONSE (CHAT):
(:type :request :target :emacs :payload (:action :insert-at-end :buffer \"*org-agent-chat*\" :text \"* <Your Org-mode Response Here>\"))

EXAMPLE OF A GOOD RESPONSE (SHELL EXECUTION):
(:type :request :target :shell :payload (:cmd \"ls -la\"))" assistant user))))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-chat
  :priority 100
  :trigger #'trigger-skill-chat
  :neuro #'neuro-skill-chat
  :symbolic #'verify-skill-chat)
#+end_src