memex/notes/org-skill-chat.org

SKILL: Chat Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Chat Event Triggering
    • Persona-Driven Response Generation
    • Emacs Buffer Insertion Verification
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • Event Perception
  • Symbolic Verification
  • Neural Response Generation
• Registration

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)

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)

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

(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.")

Phase D: Build (Implementation)

Event Perception

(defun trigger-skill-chat (context)
  (let* ((payload (getf context :payload))
         (sensor (getf payload :sensor)))
    (eq sensor :chat-message)))

Symbolic Verification

(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)))))

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.

(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))))

Registration

(defskill :skill-chat
  :priority 100
  :trigger #'trigger-skill-chat
  :neuro #'neuro-skill-chat
  :symbolic #'verify-skill-chat)