@almadar/std 16.237.0 → 16.238.0

package/behaviors/lolo/agent/atoms/std-agent-session.lolo

@@ -1,143 +1,267 @@
-app std-agent-session "1.0.0"
-"Wraps session/read-spec + session/write-spec + session/read-history — orbital session data."
+app std-agent-session "2.0.0"
+"std-agent-session — the persisted conversation with an in-app assistant. Owns AgentMessage rows (role, content, ownerId stamped with the real @user, createdAt). SEND stores the user's message, reloads the thread and emits CONVERSE with the whole conversation, oldest first, for std-agent-tool-loop to answer; REPLIED stores the assistant's reply and redraws; REPLY_FAILED redraws the conversation (the tool loop shows the error). Rows are meant to be private to their owner: owner-scoped access needs an [identity] roster, so the binding organism declares the @read/@create scoping on AgentMessage — this generic atom cannot."
 
-type OrbitalSpec = { orbitalName: string, organism: string!, method: string!, deltaPrompt: string! }
-type HistoryEntry = { role: string!, content: string!, timestamp: number }
+type AgentChatMessage = {
+  role : "user" | "assistant"
+  content : string!
+}
+type AgentLink = {
+  label : string!
+  href : string!
+}
 
 orbital AgentSessionOrbital {
+  type AgentMessagesLoaded = Event { data : [AgentMessage] } "Fired when the conversation finishes loading"
+  type AgentMessagesLoadFailed = Event { error : string, code : string } "Fired when the conversation fails to load"
+  type AgentMessageSaved = Event AgentMessage "Fired after a message persists"
+  type AgentMessageSaveFailed = Event { error : string, code : string } "Fired when a message fails to persist"
 
-  entity AgentSession [runtime] {
-    orbitalName : string = ""
-    spec : OrbitalSpec = {}
-    history : [HistoryEntry] = []
-    status : "idle" | "read" | "written" = idle
+  entity AgentMessage [persistent: agentMessages] {
+    id : string!
+    ownerId : string! @description "Whose conversation this message belongs to (the real @user). The binding organism scopes @read to it." @synonyms "user, owner, account"
+    role : "user" | "assistant" @description "Who said it." @synonyms "speaker, author" = user
+    content : string! @description "What was said." @synonyms "text, message, body"
+    createdAt : number @description "When it was said (ms)." @synonyms "time, timestamp" = 0
+    draft : string @intrinsic @description "The message being typed." = ""
   }
 
-  trait SessionReader -> AgentSession [lifecycle, instance] {
-    initial: idle
-
-    state idle {
-      INIT -> idle
-        (set @entity.orbitalName "")
-        (set @entity.spec {})
-        (set @entity.history [])
-        (set @entity.status idle)
-      READ_SPEC -> reading
-        (set @entity.orbitalName ?orbitalName)
-        (session/read-spec @entity.orbitalName { emit: { success: SPEC_LOADED, failure: SPEC_LOAD_FAILED } })
+  trait AgentThread -> @rebindable AgentMessage [interaction, collection] {
+    config {
+      title : string = "Assistant"
+        @label "Title"
+        @description "Heading above the conversation."
+        @tier "presentation"
+      placeholder : string = "Ask the assistant…"
+        @label "Message placeholder"
+        @tier "presentation"
+      links : [AgentLink] = []
+        @label "Links above the conversation"
+        @description "Related pages (e.g. the run history), shown under the title."
+        @tier "presentation"
     }
+    initial: loading
 
-    state reading {
-      SPEC_LOADED -> loadingHistory
-        (set @entity.spec ?result)
-        (session/read-history @entity.orbitalName { emit: { success: HISTORY_LOADED, failure: HISTORY_LOAD_FAILED } })
-      SPEC_LOAD_FAILED -> idle
-        (set @entity.status idle)
+    state loading {
+      INIT -> loading
+        (fetch AgentMessage {
+          emit: { failure: AgentMessagesLoadFailed, success: AgentMessagesLoaded }
+        })
+        (render-ui main {
+          type: stack
+          direction: vertical
+          gap: lg
+          children: [{ type: skeleton, variant: header }, { type: skeleton, variant: list, rows: 6 }]
+        })
+      AgentMessagesLoaded -> chatting
+        (render-ui main {
+          children: [{
+            content: @config.title
+            type: typography
+            variant: h4
+          }, {
+            children: (array/map @config.links (fn item {
+              href: @item.href
+              label: @item.label
+              type: button
+              variant: ghost
+            }))
+            direction: horizontal
+            gap: sm
+            type: stack
+          }, {
+            entity: (array/sort ?data createdAt asc)
+            fields: []
+            gap: sm
+            renderItem: (fn item {
+              children: [{
+                label: @item.role
+                size: sm
+                type: badge
+                variant: neutral
+              }, {
+                content: @item.content
+                type: typography
+                variant: body
+              }]
+              direction: vertical
+              gap: xs
+              type: stack
+            })
+            type: data-list
+          }, {
+            children: [{
+              aria-label: "Message"
+              onChange: EDIT_MESSAGE
+              placeholder: @config.placeholder
+              type: textarea
+            }, {
+              action: SEND_DRAFT
+              icon: send
+              label: Send
+              type: button
+              variant: primary
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          }]
+          direction: vertical
+          gap: md
+          type: stack
+        })
+      AgentMessagesLoadFailed -> chatting
+        (render-ui main {
+          message: ?error
+          type: alert
+          variant: error
+        })
     }
 
-    state loadingHistory {
-      HISTORY_LOADED -> read
-        (set @entity.history ?result)
-        (set @entity.status read)
-        (emit SPEC_READ { spec: @entity.spec, history: @entity.history })
-      HISTORY_LOAD_FAILED -> idle
-        (set @entity.status idle)
+    state chatting {
+      INIT -> loading
+        (fetch AgentMessage {
+          emit: { failure: AgentMessagesLoadFailed, success: AgentMessagesLoaded }
+        })
+        (render-ui main {
+          type: stack
+          direction: vertical
+          gap: lg
+          children: [{ type: skeleton, variant: header }, { type: skeleton, variant: list, rows: 6 }]
+        })
+      EDIT_MESSAGE -> chatting
+        (set @entity.draft ?value)
+      SEND_DRAFT -> waiting when (not ["=", (str/default @entity.draft ""), ""])
+        (persist create AgentMessage {
+          ownerId: @user.id
+          role: user
+          content: @entity.draft
+          createdAt: @now
+        } {
+          emit: { failure: AgentMessageSaveFailed, success: AgentMessageSaved }
+        })
+        (set @entity.draft "")
+      SEND -> waiting when (not ["=", (str/default ?message ""), ""])
+        (persist create AgentMessage {
+          ownerId: @user.id
+          role: user
+          content: ?message
+          createdAt: @now
+        } {
+          emit: { failure: AgentMessageSaveFailed, success: AgentMessageSaved }
+        })
+      REPLIED -> loading
+        (persist create AgentMessage {
+          ownerId: @user.id
+          role: assistant
+          content: ?reply
+          createdAt: @now
+        })
+        (fetch AgentMessage {
+          emit: { failure: AgentMessagesLoadFailed, success: AgentMessagesLoaded }
+        })
+      REPLY_FAILED -> loading
+        (fetch AgentMessage {
+          emit: { failure: AgentMessagesLoadFailed, success: AgentMessagesLoaded }
+        })
     }
 
-    state read {
-      INIT -> read
-        (set @entity.status read)
-      RESET -> idle
-        (set @entity.spec {})
-        (set @entity.history [])
-        (set @entity.status idle)
+    state waiting {
+      AgentMessageSaved -> waiting
+        (fetch AgentMessage {
+          emit: { failure: AgentMessagesLoadFailed, success: AgentConversationLoaded }
+        })
+        (render-ui main {
+          size: sm
+          type: spinner
+        })
+      AgentConversationLoaded -> waiting
+        (emit CONVERSE {
+          messages: (array/map (array/sort ?data createdAt asc) (fn item { role: @item.role, content: @item.content }))
+        })
+      REPLIED -> loading
+        (persist create AgentMessage {
+          ownerId: @user.id
+          role: assistant
+          content: ?reply
+          createdAt: @now
+        })
+        (fetch AgentMessage {
+          emit: { failure: AgentMessagesLoadFailed, success: AgentMessagesLoaded }
+        })
+      REPLY_FAILED -> loading
+        (fetch AgentMessage {
+          emit: { failure: AgentMessagesLoadFailed, success: AgentMessagesLoaded }
+        })
+      AgentMessageSaveFailed -> chatting
+        (render-ui main {
+          message: ?error
+          type: alert
+          variant: error
+        })
+      AgentMessagesLoadFailed -> chatting
+        (render-ui main {
+          message: ?error
+          type: alert
+          variant: error
+        })
     }
 
     emits {
-      SPEC_READ {
-        spec : OrbitalSpec!
-        history : [HistoryEntry]!
+      CONVERSE -> external {
+        messages : [AgentChatMessage]!
       }
-      SPEC_LOADED {
-        result : OrbitalSpec!
+        @description "The conversation to answer, oldest first; the last turn is the request."
+        @synonyms "ask, converse, request"
+        @tier "domain"
+      AgentConversationLoaded -> internal {
+        data : [AgentMessage]
       }
-      HISTORY_LOADED {
-        result : [HistoryEntry]!
+        @tier "internal"
+      AgentMessagesLoaded {
+        data : [AgentMessage]
       }
-    }
-
-    listens {
-      READ_SPEC {
-        orbitalName : string!
+        @description "The conversation finished loading."
+        @tier "internal"
+      AgentMessagesLoadFailed {
+        error : string
+        code : string
       }
-    }
-  }
-
-  trait SessionWriter -> AgentSession [lifecycle, instance] {
-    initial: idle
-
-    state idle {
-      INIT -> idle
-        (set @entity.orbitalName "")
-        (set @entity.spec {})
-        (set @entity.status idle)
-      WRITE_SPEC -> written
-        (set @entity.orbitalName ?orbitalName)
-        (set @entity.spec ?spec)
-        (session/write-spec @entity.orbitalName @entity.spec)
-        (set @entity.status written)
-        (emit SPEC_WRITTEN { orbitalName: @entity.orbitalName })
-    }
-
-    state written {
-      INIT -> written
-        (set @entity.status written)
-      RESET -> idle
-        (set @entity.spec {})
-        (set @entity.status idle)
-    }
-
-    emits {
-      SPEC_WRITTEN {
-        orbitalName : string!
+        @tier "internal"
+      AgentMessageSaved
+        @description "A message persisted — payload is the created AgentMessage row itself."
+        @tier "internal"
+      AgentMessageSaveFailed {
+        error : string
+        code : string
       }
-    }
-
-    listens {
-      WRITE_SPEC {
-        orbitalName : string!
-        spec : OrbitalSpec!
+        @tier "internal"
+      EDIT_MESSAGE {
+        value : string!
       }
-    }
-  }
-
-  trait SessionListener -> AgentSession [lifecycle, instance] {
-    initial: waiting
-
-    state waiting {
-      INIT -> waiting
-        (set @entity.status idle)
-      SPEC_READ -> active
-        (set @entity.status read)
-      SPEC_WRITTEN -> active
-        (set @entity.status written)
-      RESET -> waiting
-        (set @entity.status idle)
-    }
-
-    state active {
-      INIT -> active
-        (set @entity.status idle)
-      RESET -> waiting
-        (set @entity.status idle)
+        @description "The message being typed changed."
+        @tier "presentation"
+      SEND_DRAFT
+        @description "Send the typed message."
+        @synonyms "send, ask, submit"
+        @tier "domain"
     }
 
     listens {
-      SessionReader.SPEC_READ -> SPEC_READ
-      SessionWriter.SPEC_WRITTEN -> SPEC_WRITTEN
-      RESET
+      SEND {
+        message : string!
+      }
+        @description "Ask the assistant something."
+        @synonyms "ask, message, chat"
+      REPLIED {
+        reply : string!
+      }
+        @description "The assistant answered."
+      REPLY_FAILED {
+        error : string!
+      }
+        @description "The assistant could not answer."
     }
   }
 
-  page "/agent-session" as AgentSessionPage -> SessionReader, SessionWriter, SessionListener
+  page "/agent-session" as AgentSessionPage -> AgentThread
 }

package/behaviors/lolo/agent/atoms/std-agent-tool-loop.lolo

@@ -1,116 +1,122 @@
-app std-agent-tool-loop "1.0.0"
-"Agent tool-loop molecule — call-tools, check response, emit result for iteration."
+app std-agent-tool-loop "2.0.0"
+"std-agent-tool-loop — answers a conversation by operating the running app as the caller, through `call-service llm call-tools`. The `tools` allowlist names declared external inputs (addressed like a listens source: `Trait.EVENT`, `Orbital.Trait.EVENT`) and entities to read; each input fires as the signed-in user through the ordinary dispatch (guards and entity policies apply) and each read returns only the rows the caller may read. Headless: the conversation UI (std-agent-session) shows the reply; a failure shows as a toast. CONVERSE carries the conversation (and optionally what std-agent-memory recalled); REPLIED carries the reply, every tool step and the token usage; REPLY_FAILED carries the error. Compose with std-agent-session (the conversation) and std-agent-trace (the step record)."
 
-type LlmToolCall = { id: string!, type: "function", function: { name: string!, arguments: string! } }
-;; JSON Schema is recursive (@almadar/core JsonSchema: properties/items/$defs self-reference)
-;; and .lolo has no recursive-JSON type; this deliberately partial shape declares only the
-;; always-scalar top-level keys and leaves the recursive keys undeclared (honest, not checked).
-type LlmToolSchema = { type: string, description: string }
-type LlmMessage = { role: string!, content: string!, toolCalls: [LlmToolCall], toolCallId: string }
-type LlmToolDef = { name: string!, description: string!, schema: LlmToolSchema }
+type AgentTool = {
+  event : event
+  read : string
+}
+type AgentChatMessage = {
+  role : "user" | "assistant"
+  content : string!
+}
+type AgentStep = {
+  kind : "input" | "read" | "invalid"
+  target : string!
+  args : string!
+  ok : boolean!
+  detail : string
+}
+type AgentUsage = {
+  promptTokens : number!
+  completionTokens : number!
+  totalTokens : number!
+  modelCalls : number!
+}
 
 orbital AgentToolLoopOrbital {
-
-  entity ToolLoop [runtime] {
-    messages : [LlmMessage] = []
-    tools : [LlmToolDef] = []
-    response : string = ""
-    iterations : number = 0
-    status : "idle" | "calling" | "done" = idle
+  entity AgentTurn [runtime] {
+    id : string!
+    status : "idle" | "thinking" | "answered" | "failed" @description "Where the current turn is." = idle
+    reply : string @description "The last reply." = ""
+    error : string @description "Why the last turn failed." = ""
   }
 
-  trait ToolLoopExecution -> ToolLoop [lifecycle, instance] {
+  trait AgentToolLoop -> AgentTurn [interaction] {
+    config {
+      tools : [AgentTool] = []
+        @label "What may the assistant do?"
+        @description "The declared inputs it may fire (`{ event: Trait.EVENT }`) and the entities it may read (`{ read: Entity }`), as the signed-in user."
+        @synonyms "allowlist, abilities, actions, permissions"
+        @tier "domain"
+      instructions : string = "You operate this app for the signed-in user. Use the tools to act and to look things up; when a tool reports that something was refused or denied, say so plainly."
+        @label "How should the assistant behave?"
+        @description "Standing instructions sent with every conversation."
+        @synonyms "system prompt, persona, guidance"
+        @tier "domain"
+      maxSteps : number = 8
+        @label "Model round-trips per request"
+        @description "How many model calls one request may take before it fails."
+        @tier "policy"
+    }
     initial: idle
 
     state idle {
       INIT -> idle
-        (set @entity.messages [])
-        (set @entity.tools [])
-        (set @entity.response "")
-        (set @entity.iterations 0)
         (set @entity.status idle)
-      EXECUTE -> calling
-        (set @entity.messages ?messages)
-        (set @entity.tools ?tools)
-        (llm/call-tools @entity.messages @entity.tools { emit: { success: TOOLS_CALLED_1, failure: TOOLS_FAILED_1 } })
+      CONVERSE -> thinking
+        (set @entity.status thinking)
+        (call-service llm call-tools {
+          messages: ?messages
+          tools: @config.tools
+          instructions: (if ["=", (str/default ?context ""), ""] @config.instructions (str/concat @config.instructions "\n\nWhat you remember that may be relevant:\n" ?context))
+          maxSteps: @config.maxSteps
+        } {
+          emit: { failure: ASK_FAILED, success: ANSWERED }
+        })
     }
 
-    state calling {
-      TOOLS_CALLED_1 -> done
-        (set @entity.response ?result)
-        (set @entity.iterations (+ @entity.iterations 1))
-        (set @entity.status done)
-        (emit LOOP_STEP { response: @entity.response, iteration: @entity.iterations })
-      TOOLS_FAILED_1 -> done
-        (set @entity.response "")
-        (set @entity.status done)
-      TOOLS_CALLED_2 -> done
-        (set @entity.response ?result)
-        (set @entity.iterations (+ @entity.iterations 1))
-        (set @entity.status done)
-        (emit LOOP_STEP { response: @entity.response, iteration: @entity.iterations })
-      TOOLS_FAILED_2 -> done
-        (set @entity.response "")
-        (set @entity.status done)
-    }
-
-    state done {
-      INIT -> done
-        (set @entity.status done)
-      CONTINUE -> calling
-        (llm/call-tools @entity.messages @entity.tools { emit: { success: TOOLS_CALLED_2, failure: TOOLS_FAILED_2 } })
-      RESET -> idle
-        (set @entity.messages [])
-        (set @entity.tools [])
-        (set @entity.response "")
-        (set @entity.iterations 0)
-        (set @entity.status idle)
+    state thinking {
+      ANSWERED -> idle
+        (set @entity.status answered)
+        (set @entity.reply ?reply)
+        (emit REPLIED { reply: ?reply, steps: ?steps, usage: ?usage })
+      ASK_FAILED -> idle
+        (set @entity.status failed)
+        (set @entity.error ?error)
+        (emit REPLY_FAILED { error: ?error })
+        (render-ui toast {
+          message: ?error
+          type: alert
+          variant: error
+        })
     }
 
     emits {
-      LOOP_STEP {
-        response : string!
-        iteration : number!
+      REPLIED -> external {
+        reply : string!
+        steps : [AgentStep]!
+        usage : AgentUsage!
       }
-      TOOLS_CALLED_1 {
-        result : string!
+        @description "The assistant answered; carries every tool step it took and the tokens it used."
+        @synonyms "answered, responded, done"
+        @tier "domain"
+      REPLY_FAILED -> external {
+        error : string!
       }
-      TOOLS_CALLED_2 {
-        result : string!
+        @description "The assistant could not answer (model unavailable, or out of steps)."
+        @synonyms "failed, error, gave up"
+        @tier "domain"
+      ANSWERED -> internal {
+        reply : string!
+        steps : [AgentStep]!
+        usage : AgentUsage!
       }
-    }
-
-    listens {
-      EXECUTE {
-        messages : [LlmMessage]!
-        tools : [LlmToolDef]!
+        @tier "internal"
+      ASK_FAILED -> internal {
+        error : string!
       }
-      CONTINUE
-    }
-  }
-
-  trait ToolLoopListener -> ToolLoop [lifecycle, instance] {
-    initial: waiting
-
-    state waiting {
-      INIT -> waiting
-        (set @entity.status idle)
-      LOOP_STEP -> active
-        (set @entity.status done)
-    }
-
-    state active {
-      INIT -> active
-        (set @entity.status done)
-      RESET -> waiting
-        (set @entity.status idle)
+        @tier "internal"
     }
 
     listens {
-      ToolLoopExecution.LOOP_STEP -> LOOP_STEP
-      RESET
+      CONVERSE {
+        messages : [AgentChatMessage]!
+        context : string
+      }
+        @description "Answer this conversation; the last turn is the request. `context` is what the assistant remembers that may be relevant."
+        @synonyms "ask, chat, request"
     }
   }
 
-  page "/agent-tool-loop" as AgentToolLoopPage -> ToolLoopExecution, ToolLoopListener
+  page "/agent-tool-loop" as AgentToolLoopPage -> AgentToolLoop
 }