@lowdefy/docs-content 0.0.0-experimental-20260929101721 → 0.0.0-experimental-20260929135001

package/content/actions/setglobal.md

@@ -8,6 +8,8 @@ The `SetGlobal` action sets values to the `global` object. It takes an object as
 This is useful if you need to set a value that needs to be available across multiple pages in the app, like the id of a currently selected
 object. `SetGlobal` works just like [`SetState`](/SetState), except it sets to the `global` object and not `state`.
 
+To set global values once when the app loads, before the first page's events run, use `SetGlobal` in the app [`onInit` or `onInitAsync` events](/events-and-actions#app-events).
+
 #### Parameters
 
 ###### object

package/content/agents/agent-endpoint-tools.md

@@ -162,6 +162,30 @@ agents:
         confirm: true
 ```
 
+## Knowing the Calling Agent
+
+A tool endpoint can read which agent called it with the [`_agent`](/_agent) operator: `_agent: id` is the agent's `id`, `_agent: conversationId` the chat's conversation id. Lowdefy sets both from the running agent, so the model cannot set or hide them through the tool's input. Endpoints the tool endpoint calls in turn see the same agent. On a call that did not come from an agent, `_agent` returns `null`.
+
+```yaml
+api:
+  - id: create-support-ticket
+    type: Api
+    # ...
+    routine:
+      - id: insert
+        type: MongoDBInsertOne
+        connectionId: tickets_db
+        properties:
+          doc:
+            subject:
+              _payload: subject
+            createdBy:
+              userId:
+                _user: id
+              agentId:
+                _agent: id
+```
+
 ## Reserved Tool Names
 
 Lowdefy registers a small set of platform tools automatically (for example, `update-page-state`, which the [`AgentChat`](/AgentChat#shared-state) block wires up when `sharedState` is set). The following tool names are reserved and cannot be used as endpoint ids or sub-agent ids — the build will fail if one is encountered:

package/content/concepts/events-and-actions.md

@@ -281,7 +281,7 @@ Set `bubble: true` on the inner event to also run the events of the blocks aroun
                 selected: true
 ```
 
-Only events fired by the same browser event are skipped. Events that run from actions, requests or timers are never affected. Inside an `AgGrid`, clicks on a cell's buttons, links, menus, inputs or selection checkbox fire only that control's event, never `onRowClick` or `onCellClick`.
+Only blocks the browser event passed through, around the block that handled it, are skipped. Other blocks' events are never affected, nor are events that run from actions, requests or timers, or events of a block an action called a method on: a `Table` next to the button, or holding it in its toolbar, still fires `onSelectionChange` after the button's `CallMethod` cleared its selection. Inside an `AgGrid`, clicks on a cell's buttons, links, menus, inputs or selection checkbox fire only that control's event, never `onRowClick` or `onCellClick`.
 
 ## Keyboard Shortcuts
 
@@ -368,6 +368,52 @@ events:
           _event: width
 ```
 
+## App events
+
+Events can also be defined for the whole app, in the `events` object at the root of `lowdefy.yaml`. App events run once each time the app is loaded in the browser, whichever page is opened first, and do not run again when the user navigates between pages. Opening the app in a new tab, or reloading the browser, loads the app again. App events are a good place to set up [`global`](/page-and-app-state) values that every page uses, like user settings fetched from an [API endpoint](/lowdefy-api).
+
+- `onInit`: Runs before the first page's own events. The page stays in its loading state, rendering only the progress bar, until the app `onInit` actions have finished, so the first page's `onInit` can read the values it set with [`_global`](/_global).
+- `onInitAsync`: Runs once the app `onInit` has finished, without blocking the page. The first page's events do not wait for it, and pages re-render when it sets `global` values.
+
+###### Load user settings when the app loads:
+```yaml
+# lowdefy.yaml
+global:
+  settings: null
+events:
+  onInit:
+    - id: set_user
+      type: SetGlobal
+      params:
+        userName:
+          _user: name
+  onInitAsync:
+    try:
+      - id: fetch_settings
+        type: CallAPI
+        params:
+          endpointId: user_settings
+      - id: set_settings
+        type: SetGlobal
+        params:
+          settings:
+            _actions: fetch_settings.response.response
+    catch:
+      - id: warn
+        type: DisplayMessage
+        params:
+          content: Could not load your settings.
+          status: warning
+pages:
+  # ...
+```
+
+App events run outside any page, so page state, inputs, requests, blocks and subscriptions are not available to them. The build fails if an app event uses the `CallMethod`, `Request`, `Reset`, `ResetValidation`, `SetFocus`, `SetState`, `Subscribe`, `Unsubscribe` or `Validate` actions, or the `_input`, `_request`, `_request_details`, `_state` or `_websocket` operators. Use [`CallAPI`](/CallAPI) to fetch data, [`SetGlobal`](/SetGlobal) to store it, and operators like [`_user`](/_user), [`_url_query`](/_url_query), [`_global`](/_global) and [`_actions`](/_actions) to read values. A [`Link`](/Link) action can redirect the user, for example to an onboarding page.
+
+App event errors are handled like page event errors: the error message is displayed, the error is logged, and the `catch` actions run. A failed app `onInit` does not stop the page from loading, and the app `onInitAsync` still runs after it. App events do not support `shortcut`.
+
+The app events config is sent to the browser with the rest of the app config, like `global`, so do not put secrets in it.
+
 ## Action types
 
 The following actions can be used:
@@ -405,3 +451,4 @@ See additional action type available under the Actions tab in the menu.
 - The `onOnline` and `onOffline` events are triggered when the browser reports that the network connection was regained or lost.
 - The `onResize` event is triggered when the window is resized, debounced by 150ms.
 - Browser lifecycle events are never triggered on the initial page load, and are removed when the user navigates away from the page.
+- App events, defined in the root `events` object, run once per app load: the app `onInit` runs before the first page's events and keeps the page in loading, and the app `onInitAsync` runs after it without blocking the page.

package/content/concepts/lowdefy-schema.md

@@ -15,6 +15,7 @@ The root schema for a Lowdefy app is:
 - `config: object`: An object with app configuration like the home page pageId.
 - `auth: object` An object with authentication and authorization configuration.
 - `global: object`: A data object that can be accessed anywhere in the app using the [`_global`](/_global) operator.
+- `events: object`: App events, `onInit` and `onInitAsync`, that run once each time the app loads in the browser. See [App events](/events-and-actions#app-events).
 - `connections: object[]`: An array of [`connection`](/connections-and-requests) objects.
 - `plugins: object[]`: An array of `plugin` objects to customize and add block types.
 - `modules: object[]`: An array of module entries. Each module references a reusable configuration package distributed via GitHub or local file paths. See [Modules](/modules) for details.
@@ -80,6 +81,8 @@ See more about how user authentication and authorization [here](/users-introduct
 
 In a Lowdefy app, you can define global variables in the __global__ object, which can be accessed using the [`_global`](/_global) operator, and modified using the [`SetGlobal`](/SetGlobal) action. This is a good place to store data or configuration that is used over various pages throughout the app, for example, user preferences that can be modified using `SetGlobal` on one page and easily referenced on all others.
 
+The app [`events`](/events-and-actions#app-events) `onInit` and `onInitAsync` run once each time the app loads, before the first page's own events, and are a good place to set global values, for example user settings fetched with a [`CallAPI`](/CallAPI) action.
+
 ## Connections
 
 In a Lowdefy app you can integrate with other services like API's or databases using `connections` and `requests`. Use connections to configure the settings to a service, for example, settings such as urls or [`secrets`](/secrets) like passwords or API keys. Requests use connections to interact with external services, for example, inserting a data record or executing a query on a database, or simply calling an API end-point.