@almadar/std 16.239.0 → 16.242.0

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

@@ -1,9 +1,10 @@
 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); STEP carries each step live while it works (a model call, a tool it used, what the app answered) to the asking tab; REPLIED carries the reply, every step and the token usage; REPLY_FAILED carries the error. Compose with std-agent-session (the conversation) and std-agent-trace (the step record)."
+"std-agent-tool-loop — answers a conversation by operating the running app as the caller, through `call-service llm call-tools`. Its `tools` are `{ scope: declared }` (every declared external input plus a read over every persisted entity), or named declared 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); ASSISTANT_STEP carries each step live while it works (a model call, a tool it used, what the app answered) to the asking tab; ASSISTANT_REPLIED carries the reply, every step and the token usage; ASSISTANT_REPLY_FAILED carries the error. These names are the assistant contract std-agent-session's conversation hears from any orbital. Compose with std-agent-session (the conversation) and std-agent-trace (the step record)."
 
 type AgentTool = {
   event : event
   read : string
+  scope : "declared"
 }
 type AgentChatMessage = {
   role : "user" | "assistant"
@@ -94,7 +95,7 @@ orbital AgentToolLoopOrbital {
           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, onMessage: STEP }
+          emit: { failure: ASK_FAILED, success: ANSWERED, onMessage: ASSISTANT_STEP }
         })
     }
 
@@ -102,11 +103,11 @@ orbital AgentToolLoopOrbital {
       ANSWERED -> idle
         (set @entity.status answered)
         (set @entity.reply ?reply)
-        (emit REPLIED { reply: ?reply, steps: ?steps, usage: ?usage })
+        (emit ASSISTANT_REPLIED { reply: ?reply, steps: ?steps, usage: ?usage })
       ASK_FAILED -> idle
         (set @entity.status failed)
         (set @entity.error ?error)
-        (emit REPLY_FAILED { error: ?error })
+        (emit ASSISTANT_REPLY_FAILED { error: ?error })
         (render-ui toast {
           message: ?error
           type: alert
@@ -115,13 +116,13 @@ orbital AgentToolLoopOrbital {
     }
 
     emits {
-      STEP -> external {
+      ASSISTANT_STEP -> external {
         activity : AgentActivity!
       }
         @description "One thing the assistant just did, live while it works: a model call, a tool it used, or what the app answered. Delivered to the asking tab only."
         @synonyms "progress, activity, trace step, working"
         @tier "domain"
-      REPLIED -> external {
+      ASSISTANT_REPLIED -> external {
         reply : string!
         steps : [AgentActivity]!
         usage : AgentUsage!
@@ -129,7 +130,7 @@ orbital AgentToolLoopOrbital {
         @description "The assistant answered; carries every tool step it took and the tokens it used."
         @synonyms "answered, responded, done"
         @tier "domain"
-      REPLY_FAILED -> external {
+      ASSISTANT_REPLY_FAILED -> external {
         error : string!
       }
         @description "The assistant could not answer (model unavailable, or out of steps)."

package/behaviors/lolo/agent/organisms/std-agent-assistant.lolo

@@ -1,14 +1,16 @@
 app std-agent-assistant "2.0.0"
-"std-agent-assistant — an in-app assistant that operates the running app for the signed-in user. A floating button opens it in a side panel docked beside the page (std-panel-launcher; a side sheet on small screens), where the conversation shows every step the assistant takes live as it works. List AssistantDock with the assistant's traits on each page that should carry the button. One request flows down a chain of std agent atoms on the bus: the conversation (std-agent-session) SENDs → CONVERSE → std-agent-context bounds it → std-agent-memory adds what it recalls → std-agent-tool-loop answers it through `call-service llm call-tools`, firing only the inputs and reading only the entities the `tools` allowlist names, as the signed-in user → REPLIED goes back to the conversation, to memory (remembered) and to std-agent-trace (the run record). Import the orbital and supply the allowlist: `orbital Assistant = Agent.orbitals.AgentAssistantOrbital { config { tools: [{ event: TaskOrbital.TaskPersistor.DO_CREATE }, { read: Task }], instructions: \"…\" } }`. The conversation, memory and run records live in AgentRecordsOrbital; retarget them onto your own owner-scoped entities (`ownerId` a relation to your [identity] roster, with @read/@create) with `entities { AgentMessage: …, AgentMemory: …, AgentRun: … }`."
+"std-agent-assistant — an in-app assistant that operates the running app for the signed-in user. Each section's floating button opens it in a side panel docked beside the page (std-panel-launcher; a side sheet on small screens), where the conversation shows every step the assistant takes live as it works; /assistant is the same conversation as a full page, in the app's own shell (pass `appName` and `navItems`); past conversations and what the assistant remembers open in place from its toolbar (Back returns to the chat), on either surface. One request flows down a chain of std agent atoms on the bus: the conversation (std-agent-session) SENDs → CONVERSE → std-agent-context bounds it → std-agent-memory adds what it recalls → std-agent-tool-loop answers it through `call-service llm call-tools`, firing only the inputs and reading only the entities its `tools` allow, as the signed-in user → ASSISTANT_REPLIED goes back to the conversation, to memory (remembered) and to std-agent-trace (the run record). By default the tools are the program's own declarations: every `-> external` input (its @description is the tool text) and a read over every persisted entity, so composing building blocks composes the assistant's abilities. Any section's page gets the assistant with two traits, `XAssistant = AgentSession.traits.AgentConversation` and a std-panel-launcher dock: the conversation speaks the ASSISTANT_* contract from any orbital, so the assistant needs no per-section wiring. Import the orbital once per app: `orbital Assistant = Agent.orbitals.AgentAssistantOrbital { config { instructions: \"…\" } }`. The conversation, memory and run records live in AgentRecordsOrbital; retarget them onto your own owner-scoped entities (`ownerId` a relation to your [identity] roster, with @read/@create) with `entities { AgentMessage: …, AgentMemory: …, AgentRun: …, AgentChat: … }`. The conversation is kept across pages and reloads (each person's most recently used conversation is the current one);"
 
 type AgentTool = {
   event : event
   read : string
+  scope : "declared"
 }
 type AgentLink = {
   label : string!
   href : string!
 }
+type NavItem = { label : string!, href : string!, icon : string, badge : string, children : [NavItem], roles : [string] }
 
 orbital AgentAssistantOrbital {
   uses Session from "std/behaviors/std-agent-session"
@@ -16,12 +18,12 @@ orbital AgentAssistantOrbital {
   uses Memory from "std/behaviors/std-agent-memory"
   uses Loop from "std/behaviors/std-agent-tool-loop"
   uses Trace from "std/behaviors/std-agent-trace"
-  uses Launcher from "std/behaviors/std-panel-launcher"
+  uses Shell from "std/behaviors/std-app-layout"
 
   config {
-    tools : [AgentTool] = []
+    tools : [AgentTool] = [{ scope: declared }]
       @label "What may the assistant do?"
-      @description "The declared inputs it may fire (`{ event: Trait.EVENT }` / `{ event: Orbital.Trait.EVENT }`) and the entities it may read (`{ read: Entity }`), as the signed-in user."
+      @description "As the signed-in user: `{ scope: declared }` (the default) gives it every external input the program declares and a read over every persisted entity, so each building block's declared inputs become its abilities; or list them — `{ event: Orbital.Trait.EVENT }` for one input, `{ read: Entity }` for one entity."
       @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."
@@ -38,17 +40,22 @@ orbital AgentAssistantOrbital {
     recallLimit : number = 3
       @label "Memories recalled per request"
       @tier "policy"
-    links : [AgentLink] = [{ label: "Run history", href: "/assistant/runs" }, { label: "What I remember", href: "/assistant/memory" }]
+    links : [AgentLink] = [{ label: "Run history", href: "/assistant/runs" }]
       @label "Links above the conversation"
-      @description "The pages showing the assistant's run history and memory."
+      @description "Related pages, e.g. the assistant's run history."
       @tier "presentation"
-    title : string = "Assistant"
-      @label "Panel title"
+    appName : string = "Assistant"
+      @label "App name in the assistant page's header"
+      @description "Pass the app's own name so the assistant page matches the rest of the app."
       @tier "presentation"
-    buttonLabel : string = "Open the assistant"
-      @label "Button label"
-      @description "What the floating button does, read to screen readers and shown as its tooltip."
+    navItems : [NavItem] = []
+      @label "Sidebar navigation on the assistant page"
+      @description "Pass the app's own navItems so the assistant page keeps the app's sidebar."
       @tier "presentation"
+    viewerRole : string = ""
+      @label "Viewer role on the assistant page"
+      @description "The role the assistant page's sidebar items and their `roles` are checked against. Bind `@user.role` in an app whose identity carries a role; left empty, only items with no `roles` show."
+      @tier "policy"
   }
 
   entity AgentAssistant [runtime] {
@@ -60,8 +67,20 @@ orbital AgentAssistantOrbital {
       CONVERSE: REQUEST_CONTEXT
     }
     listens {
-      AssistantConversation.SEND -> SEND
-      AssistantLoop.REPLIED -> REPLIED
+      AssistantChatKeeper.ASSISTANT_CHAT_OPENED -> OPEN_CHAT
+      AssistantChatKeeper.ASSISTANT_SEND_IN_CHAT -> SEND_IN_CHAT
+      AssistantChatKeeper.ASSISTANT_REPLY_IN_CHAT -> REPLY_IN_CHAT
+    }
+  }
+
+  trait AssistantChatKeeper = Session.traits.AgentChatKeeper -> AgentChat {
+    listens {
+      *.ASSISTANT_SEND -> SEND
+      *.ASSISTANT_HISTORY_REQUESTED -> LOAD_HISTORY
+      *.ASSISTANT_NEW_CHAT -> NEW_CHAT
+      *.ASSISTANT_CHAT_SELECTED -> SELECT_CHAT
+      *.ASSISTANT_CHATS_REQUESTED -> LIST_CHATS
+      AssistantLoop.ASSISTANT_REPLIED -> REPLIED
     }
   }
 
@@ -69,21 +88,19 @@ orbital AgentAssistantOrbital {
     config {
       links: @config.links
     }
-    listens {
-      AssistantThread.AgentMessagesLoaded -> THREAD_LOADED
-      AssistantThread.THREAD_FAILED -> REPLY_FAILED
-      AssistantLoop.STEP -> STEP
-      AssistantLoop.REPLIED -> REPLIED
-      AssistantLoop.REPLY_FAILED -> REPLY_FAILED
-    }
   }
 
-  trait AssistantDock = Launcher.traits.PanelLauncher {
+  ;; The full assistant page: the same conversation as the side panel, in the
+  ;; app's own shell.
+  trait AssistantLayout = Shell.traits.AppLayout {
     config {
-      contentTrait: @trait.AssistantConversation
-      title: @config.title
-      label: @config.buttonLabel
-      icon: message-circle
+      viewerRole: @config.viewerRole
+      viewerName: @user.name
+      viewerEmail: @user.email
+      appName: @config.appName
+      navItems: @config.navItems
+      contentTrait: <trait.AssistantConversation />
+      contentClassName: "mx-auto flex w-full max-w-3xl flex-col h-[calc(100vh-9rem)] min-h-0"
     }
   }
 
@@ -102,7 +119,8 @@ orbital AgentAssistantOrbital {
     }
     listens {
       AssistantContext.COMPACTED -> RECALL
-      AssistantLoop.REPLIED -> REMEMBER
+      AssistantLoop.ASSISTANT_REPLIED -> REMEMBER
+      *.ASSISTANT_MEMORIES_REQUESTED -> LIST
     }
   }
 
@@ -119,19 +137,18 @@ orbital AgentAssistantOrbital {
 
   trait AssistantTrace = Trace.traits.AgentTraceRecorder -> AgentRun {
     listens {
-      AssistantLoop.REPLIED -> REPLIED
-      AssistantLoop.REPLY_FAILED -> REPLY_FAILED
+      AssistantLoop.ASSISTANT_REPLIED -> REPLIED
+      AssistantLoop.ASSISTANT_REPLY_FAILED -> REPLY_FAILED
     }
   }
 
-  page "/assistant" as AssistantPage -> AssistantDock, AssistantThread, AssistantContext, AssistantMemory, AssistantLoop, AssistantTrace
+  page "/assistant" as AssistantPage -> AssistantLayout, AssistantThread, AssistantChatKeeper, AssistantContext, AssistantMemory, AssistantLoop, AssistantTrace
 }
 
 ;; The assistant's records live outside AgentAssistantOrbital, so a consumer
 ;; importing that orbital retargets them onto its own owner-scoped entities:
 ;; `entities { AgentMessage: MyMessage, AgentMemory: MyMemory, AgentRun: MyRun }`.
 orbital AgentRecordsOrbital {
-  uses Memory from "std/behaviors/std-agent-memory"
   uses Trace from "std/behaviors/std-agent-trace"
 
   entity AgentRun [persistent: agentRuns] {
@@ -143,6 +160,15 @@ orbital AgentRecordsOrbital {
   entity AgentMemory [persistent: agentMemories] {
     id : string!
   }
+  entity AgentChat [persistent: agentChats] {
+    id : string!
+    ownerId : string!
+    title : string = ""
+    startedAt : number = 0
+    lastActiveAt : number = 0
+    pendingMessage : string @intrinsic = ""
+    pendingReply : string @intrinsic = ""
+  }
 
   trait AgentRunHistory = Trace.traits.AgentRunBrowse -> AgentRun {
     listens {
@@ -150,12 +176,5 @@ orbital AgentRecordsOrbital {
     }
   }
 
-  trait AgentMemoryList = Memory.traits.AgentMemoryBrowse -> AgentMemory {
-    listens {
-      AgentAssistantOrbital.AssistantMemory.MEMORY_STORED -> MEMORY_STORED
-    }
-  }
-
   page "/assistant/runs" as AssistantRunsPage -> AgentRunHistory
-  page "/assistant/memory" as AssistantMemoryPage -> AgentMemoryList
 }

package/behaviors/lolo/infra/atoms/std-page-open.lolo

@@ -0,0 +1,59 @@
+app std-page-open "1.0.0"
+"std-page-open — opens a URL in a new, focused browser tab and reports the tab. Wire OPEN to something the person does (a button or a row action), so a page only ever opens because they asked for it. Needs a host with the `page` service (a browser extension)."
+
+orbital PageOpenOrbital {
+  entity PageOpenRecord [runtime] {
+    opened : number @description "How many pages were opened" @synonyms "count" = 0
+    errorMessage : string @description "Why the last page could not be opened; blank = none" @synonyms "error, failure reason" = ""
+  }
+
+  trait PageOpen -> PageOpenRecord [interaction, instance] {
+    initial: ready
+
+    config {
+      statusSlot : slot = main
+        @label "Status slot"
+        @description "Where the atom shows its one-line status; an organism running it in the background sends it to `system`"
+        @synonyms "status area, slot"
+        @tier "presentation"
+    }
+
+    state ready {
+      INIT -> ready
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: "Ready to open pages" })
+      OPEN -> ready
+        (call-service "page" "openTab" { url: ?url, active: true }
+          { emit: { success: TAB_OPENED, failure: OPEN_CALL_FAILED } })
+      TAB_OPENED -> ready
+        (set @entity.opened (+ @entity.opened 1))
+        (emit OPENED { tab: ?tab })
+      OPEN_CALL_FAILED -> ready
+        (set @entity.errorMessage ?error)
+        (emit OPEN_FAILED { error: ?error })
+        (notify error (str/concat "Couldn't open the page — " ?error))
+    }
+
+    emits {
+      TAB_OPENED { tab : number! }
+        @description "The page service opened the tab"
+        @tier "secondary"
+      OPEN_CALL_FAILED { error : string! }
+        @description "The page service could not open the tab"
+        @tier "secondary"
+      OPENED -> external { tab : number! }
+        @description "The page is open in a new, focused tab"
+        @synonyms "opened, launched, visited"
+        @tier "primary"
+      OPEN_FAILED -> external { error : string! }
+        @description "The page could not be opened"
+        @tier "primary"
+    }
+
+    listens {
+      OPEN -> external { url : string! }
+        @description "Open `url` in a new, focused tab — wire it to something the person does"
+    }
+  }
+
+  page "/page-open" as PageOpenPage -> PageOpen
+}

package/behaviors/lolo/infra/atoms/std-page-search.lolo

@@ -0,0 +1,134 @@
+app std-page-search "1.0.0"
+"std-page-search — runs one search on a site in a background tab: opens `searchUrl` with the query as the `queryParam` parameter, reads up to `maxResults` elements matching `resultSelector` (waiting up to `waitMs` for the results to appear), closes the tab, and reports RESULTS with the fields read from each. One search at a time: SEARCH is accepted again once RESULTS or SEARCH_FAILED is reported. It never clicks anything. Needs a host with the `page` service (a browser extension with access to the search pages)."
+
+orbital PageSearchOrbital {
+  type PageField = {
+    selector : string
+    attr : string
+    resolve : boolean
+  }
+
+  type PageResult = {
+    elementId : string!
+    fields : Map string string
+  }
+
+  entity PageSearchRecord [runtime] {
+    query : string @description "The search being run" @synonyms "search term, terms, topic" = ""
+    tab : number @description "The background tab running the search; 0 = none" @synonyms "tab id" = 0
+    errorMessage : string @description "Why the last search failed; blank = none" @synonyms "error, failure reason" = ""
+    status : "idle" | "searching" @description "Whether a search is running" @synonyms "state, busy" = idle
+  }
+
+  trait PageSearch -> PageSearchRecord [interaction, instance] {
+    initial: idle
+
+    config {
+      statusSlot : slot = main
+        @label "Status slot"
+        @description "Where the atom shows its one-line status; an organism running it in the background sends it to `system`"
+        @synonyms "status area, slot"
+        @tier "presentation"
+      searchUrl : string = "https://example.com/search"
+        @label "Search page"
+        @description "URL of the site's search results page, without the query"
+        @synonyms "search url, results page, endpoint"
+        @tier "domain"
+      resultsMatch : string = "https://example.com/search*"
+        @label "Results pages"
+        @description "URL match pattern the results page lies in (Chrome match-pattern syntax); the search page must match it, and the extension asks for access to exactly these pages"
+        @synonyms "site, url pattern, results url"
+        @tier "domain"
+      queryParam : string = "q"
+        @label "Query parameter"
+        @description "Name of the URL parameter that carries the search terms"
+        @synonyms "query key, search parameter"
+        @tier "domain"
+      resultSelector : string = ".result"
+        @label "Result selector"
+        @description "CSS selector of one result on the results page"
+        @synonyms "result, item, card, tile"
+        @tier "domain"
+      fields : Map string PageField = {}
+        @label "Fields"
+        @description "Field name to how to read it from each result: `selector` (a descendant; absent reads the result itself), `attr` (an attribute; absent reads the text) and `resolve` (the attribute is a URL: return it absolute)"
+        @synonyms "columns, properties, extract"
+        @tier "domain"
+      maxResults : number = 10
+        @label "Results per search"
+        @description "Most results read from one search"
+        @synonyms "limit, count, how many"
+        @tier "policy"
+      waitMs : number = 8000
+        @label "Wait for results (ms)"
+        @description "How long to wait for the results page to load and its first result to appear"
+        @synonyms "timeout, wait, patience"
+        @tier "infra"
+    }
+
+    state idle {
+      INIT -> idle
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: "Ready to search" })
+      SEARCH -> searching
+        (set @entity.query ?query)
+        (set @entity.tab 0)
+        (set @entity.status searching)
+        (call-service "page" "openTab" { url: @config.searchUrl, params: (object/set {} @config.queryParam ?query), match: @config.resultsMatch, active: false }
+          { emit: { success: TAB_OPENED, failure: SEARCH_CALL_FAILED } })
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: (str/concat "Searching for " ?query) })
+    }
+
+    state searching {
+      INIT -> searching
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: (str/concat "Searching for " @entity.query) })
+      TAB_OPENED -> searching
+        (set @entity.tab ?tab)
+        (call-service "page" "query" { tab: ?tab, selector: @config.resultSelector, fields: @config.fields, limit: @config.maxResults, waitMs: @config.waitMs }
+          { emit: { success: RESULTS_READ, failure: SEARCH_CALL_FAILED } })
+      RESULTS_READ -> idle
+        (call-service "page" "closeTab" { tab: ?tab })
+        (set @entity.tab 0)
+        (set @entity.status idle)
+        (emit RESULTS { query: @entity.query, results: ?elements })
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: (str/concat "Searched for " @entity.query) })
+      SEARCH_CALL_FAILED -> idle when (> @entity.tab 0)
+        (call-service "page" "closeTab" { tab: @entity.tab })
+        (set @entity.tab 0)
+        (set @entity.errorMessage ?error)
+        (set @entity.status idle)
+        (emit SEARCH_FAILED { query: @entity.query, error: ?error })
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: (str/concat "Couldn't search: " ?error) })
+      SEARCH_CALL_FAILED -> idle when (== @entity.tab 0)
+        (set @entity.errorMessage ?error)
+        (set @entity.status idle)
+        (emit SEARCH_FAILED { query: @entity.query, error: ?error })
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: (str/concat "Couldn't search: " ?error) })
+    }
+
+    emits {
+      TAB_OPENED { tab : number! }
+        @description "The background tab for the search is open"
+        @tier "secondary"
+      RESULTS_READ { tab : number!, elements : [PageResult]! }
+        @description "The results were read from the search page"
+        @tier "secondary"
+      SEARCH_CALL_FAILED { error : string! }
+        @description "Opening the search page or reading it failed"
+        @tier "secondary"
+      RESULTS -> external { query : string!, results : [PageResult]! }
+        @description "What one search found: each result's element id and the fields read from it"
+        @synonyms "search results, found, hits"
+        @tier "primary"
+      SEARCH_FAILED -> external { query : string!, error : string! }
+        @description "The search could not be run or read"
+        @tier "primary"
+    }
+
+    listens {
+      SEARCH -> external { query : string! }
+        @description "Search the site for `query`"
+    }
+  }
+
+  page "/page-search" as PageSearchPage -> PageSearch
+}

package/behaviors/lolo/infra/atoms/std-page-treat.lolo

@@ -0,0 +1,59 @@
+app std-page-treat "1.0.0"
+"std-page-treat — applies a declared visual treatment to one element of a browser tab (hide, blur, highlight, or label it with text) or restores it, and reports which element it treated. TREAT takes the tab and element id std-page-watch reports. The treatments are a fixed, declared set: no arbitrary styles or scripts. Needs a host with the `page` service (a browser extension)."
+
+orbital PageTreatOrbital {
+  entity PageTreatRecord [runtime] {
+    treated : number @description "How many treatments were applied" @synonyms "count, applied" = 0
+    errorMessage : string @description "Why the last treatment failed; blank = none" @synonyms "error, failure reason" = ""
+  }
+
+  trait PageTreat -> PageTreatRecord [interaction, instance] {
+    initial: ready
+
+    config {
+      statusSlot : slot = main
+        @label "Status slot"
+        @description "Where the atom shows its one-line status; an organism running it in the background sends it to `system`"
+        @synonyms "status area, slot"
+        @tier "presentation"
+    }
+
+    state ready {
+      INIT -> ready
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: "Ready to treat page elements" })
+      TREAT -> ready
+        (call-service "page" "apply" { tab: ?tab, elementId: ?elementId, treatment: ?treatment, label: ?label }
+          { emit: { success: APPLIED, failure: APPLY_FAILED } })
+      APPLIED -> ready
+        (set @entity.treated (+ @entity.treated 1))
+        (emit TREATED { tab: ?tab, elementId: ?elementId, treatment: ?treatment })
+      APPLY_FAILED -> ready
+        (set @entity.errorMessage ?error)
+        (emit TREAT_FAILED { error: ?error })
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: (str/concat "Couldn't treat a page element: " ?error) })
+    }
+
+    emits {
+      APPLIED { applied : boolean!, tab : number!, elementId : string!, treatment : "hide" | "blur" | "highlight" | "label" | "restore" }
+        @description "The page service applied the treatment"
+        @tier "secondary"
+      APPLY_FAILED { error : string! }
+        @description "The page service could not apply the treatment"
+        @tier "secondary"
+      TREATED -> external { tab : number!, elementId : string!, treatment : "hide" | "blur" | "highlight" | "label" | "restore" }
+        @description "The element now shows the treatment (or, for restore, is back as it was)"
+        @synonyms "hidden, blurred, highlighted, labelled, restored"
+        @tier "primary"
+      TREAT_FAILED -> external { error : string! }
+        @description "The treatment could not be applied (the element is gone, or the tab closed)"
+        @tier "primary"
+    }
+
+    listens {
+      TREAT -> external { tab : number!, elementId : string!, treatment : "hide" | "blur" | "highlight" | "label" | "restore", label : string }
+        @description "Treat one page element; `label` is the text shown with it (for example why it was hidden)"
+    }
+  }
+
+  page "/page-treat" as PageTreatPage -> PageTreat
+}

package/behaviors/lolo/infra/atoms/std-page-watch.lolo

@@ -0,0 +1,86 @@
+app std-page-watch "1.0.0"
+"std-page-watch — watches every browser tab whose URL matches `match` for elements matching `itemSelector`, and reports each element once as ITEM with the `fields` read from it, now and as the page changes. Needs a host with the `page` service (a browser extension, which asks for access to exactly the `match` pages). Each item carries its tab and element id; compose std-page-treat to hide, blur, highlight or label it."
+
+orbital PageWatchOrbital {
+  type PageField = {
+    selector : string
+    attr : string
+    resolve : boolean
+  }
+
+  entity PageWatchRecord [runtime] {
+    watchId : string @description "Id of the attached watch" @synonyms "watch id, subscription" = ""
+    found : number @description "How many elements have been reported" @synonyms "count, items seen, reported" = 0
+    errorMessage : string @description "Why the watch could not be attached; blank = none" @synonyms "error, failure reason" = ""
+    status : "starting" | "watching" | "failed" @description "Whether the watch is attached" @synonyms "state, watching, connected" = starting
+  }
+
+  trait PageWatch -> PageWatchRecord [lifecycle, instance] {
+    initial: active
+
+    config {
+      statusSlot : slot = main
+        @label "Status slot"
+        @description "Where the atom shows its one-line status; an organism running it in the background sends it to `system`"
+        @synonyms "status area, slot"
+        @tier "presentation"
+      match : string = "https://example.com/*"
+        @label "Pages"
+        @description "URL match pattern of the tabs to watch, in Chrome match-pattern syntax (`<scheme>://<host>/<path>` with `*` wildcards)"
+        @synonyms "site, url pattern, pages, domain"
+        @tier "domain"
+      itemSelector : string = ".item"
+        @label "Item selector"
+        @description "CSS selector of the elements to report"
+        @synonyms "selector, element, card, tile, row"
+        @tier "domain"
+      fields : Map string PageField = {}
+        @label "Fields"
+        @description "Field name to how to read it from each element: `selector` (a descendant; absent reads the element itself), `attr` (an attribute; absent reads the text) and `resolve` (the attribute is a URL: return it absolute)"
+        @synonyms "columns, properties, extract, read"
+        @tier "domain"
+      itemEvent : event = "PageWatch.ITEM_FOUND"
+        @label "Item input"
+        @description "The declared input each element arrives as; it follows the trait when a composer renames it"
+        @tier "internal"
+    }
+
+    state active {
+      INIT -> active
+        (call-service "page" "watch" { match: @config.match, selector: @config.itemSelector, fields: @config.fields, event: @config.itemEvent }
+          { emit: { success: WATCHING, failure: WATCH_FAILED } })
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: "Connecting to the pages…" })
+      WATCHING -> active
+        (set @entity.watchId ?watchId)
+        (set @entity.status watching)
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: (str/concat "Watching " @config.match) })
+      WATCH_FAILED -> active
+        (set @entity.errorMessage ?error)
+        (set @entity.status failed)
+        (render-ui @config.statusSlot { type: typography, variant: body, role: status, content: (str/concat "Can't watch these pages: " ?error) })
+      ITEM_FOUND -> active
+        (set @entity.found (+ @entity.found 1))
+        (emit ITEM { tab: ?tab, elementId: ?elementId, url: ?url, fields: ?fields })
+    }
+
+    emits {
+      WATCHING { watchId : string! }
+        @description "The watch is attached"
+        @tier "secondary"
+      WATCH_FAILED -> external { error : string! }
+        @description "The watch could not be attached (no page service, or no access to the pages)"
+        @tier "primary"
+      ITEM -> external { tab : number!, elementId : string!, url : string!, fields : Map string string }
+        @description "One matching element, reported once, with the fields read from it"
+        @synonyms "element found, item seen, new item"
+        @tier "primary"
+    }
+
+    listens {
+      ITEM_FOUND -> external { tab : number!, elementId : string!, url : string!, fields : Map string string }
+        @description "One matching element, delivered by the page service"
+    }
+  }
+
+  page "/page-watch" as PageWatchPage -> PageWatch
+}