pgkiln 0.51.0 → 0.52.0

package/docs/guide/07-dynamic-actions.md

@@ -37,6 +37,7 @@ your own from a static application file.
 | `selection_change` | Rows are selected in a report with [row selection](04-pages-and-regions.md#row-selection), or another master row in a grid; the condition sees the selected values, colon separated | Region ids or static ids |
 | `before_submit` | The page is about to be submitted; a declined `confirm` keeps the page | – |
 | `custom` | JavaScript raised the event: `pgkiln.trigger('ORDER_SAVED', value)` (APEX: custom events, `apex.event.trigger`) | Event names (case-insensitive) |
+| `menu_entry` | An entry `{"label": …, "action": "NAME"}` of a [menu button](06-processing.md#menu-buttons-and-badges) was chosen (APEX: Menu entry chosen); the condition sees the entry's name ([below](#menu-entry-chosen)) | Entry names, or menu button names (any of their entries) |
 
 **The actions of one event and trigger run one after the other, in sequence order** (APEX: the true
 actions of a dynamic action), each waiting for the one before (a server action for its answer). A
@@ -79,11 +80,44 @@ actions of a dynamic action), each waiting for the one before (a server action f
 | `print` | browser | The browser's print dialog |
 | `current_position` | browser | The device's position as `latitude,longitude` (5 decimals) into the first affected item |
 | `share` | browser | The device's share sheet with the page's title, `message` and address; where there is none, the address is copied |
+| `wait_popup` | browser | Shows a modal "please wait" popup with `message` (default *Please wait…*) until `remove_wait_popup` or the next page (APEX: Show Wait Popup); [below](#wait-popup) |
+| `remove_wait_popup` | browser | Removes the wait popup (APEX: Remove Wait Popup) |
 
 Server-side actions first store `items_to_submit` in session state, run as the application's
 database role like everything else, and check the page's and the dynamic action's authorization.
 The SQL itself never reaches the browser.
 
+## Wait popup
+
+`wait_popup` covers the page with a small dialog (a spinner and `message`) while something slow
+runs, so the user doesn't click twice; `remove_wait_popup` takes it away. Because the actions of
+one event run in sequence, each waiting for the one before, two patterns cover most cases:
+
+| Sequence | Event | Action | |
+|---|---|---|---|
+| 10 | `click` on `RECALC` (a submit button) | `wait_popup` | *Recalculating…*: the popup stays until the next page arrives |
+| 10 | `click` on `CHECK` | `wait_popup` | *Checking…* |
+| 20 | `click` on `CHECK` | `execute_sql` | the Ajax call (also `set_value`, `refresh_region`, `download`, a plug-in) |
+| 30 | `click` on `CHECK` | `remove_wait_popup` | |
+
+`before_submit` → `wait_popup` shows it for every submit of the page. A submit the browser refuses
+(a required field is empty) removes it again, and so does going back to the page in the browser.
+The popup is a modal `<dialog>`: the page below can't be clicked or focused, Escape doesn't close
+it, its text is a status message that screen readers read out, and the page's `<main>` is
+`aria-busy` while it shows. It follows the theme (light and dark) and needs no inline styles or
+scripts. From JavaScript: `const done = pgkiln.waitPopup('Saving…'); … done();` (or
+`pgkiln.removeWaitPopup()`).
+
+## Menu entry chosen
+
+A [menu button](06-processing.md#menu-buttons-and-badges)'s entry can run dynamic actions instead
+of linking or submitting: `{"label": "Export", "action": "EXPORT"}`. Dynamic actions with event
+`menu_entry` and trigger `EXPORT` run when it is chosen (the menu closes first); a trigger with the
+menu button's name runs for every action entry of that menu, and a client-side condition tests the
+entry's name (`equals` `EXPORT`). Without JavaScript such an entry does nothing, like a button with
+action `da`. The HR example's page 47 has an *Actions* menu whose *Count employees* entry shows a
+wait popup around an Ajax call.
+
 ## Ajax callbacks
 
 A page process with point **ajax** (APEX: an On Demand process) runs only when JavaScript calls it by

package/docs/guide/09-reference.md

@@ -481,9 +481,10 @@ navigation entries and application processes have the same `build_option` column
 | `push_key` | The VAPID key pair of an application with [push notifications](17-mobile.md#push-notifications): `public_key`, `private_key` (encrypted with `PGKILN_SECRET_KEY`). Not exported | no |
 | `push_subscription` | Devices with notifications on: `app_id`, `username`, `endpoint` (the push service URL), the device's keys `p256dh` and `auth`, `user_agent`, `created_at`, `last_sent_at`, `failures`. Not exported | no (through `meta.has_push_subscription`) |
 | `push_message` | [Push notifications from SQL](#push-notifications-from-sql): `app_id`, `username`, `title`, `body`, `url`, `tag`, `urgency`, `ttl_s`, `status`, `attempts`, `devices`, `delivered`, `message`, `requested_by`, times. Kept 7 days, not exported | no |
-| `ai_service` | [AI services](06-processing.md#generate-text-with-ai) of the installation: `name`, `provider` (`anthropic`, `openai`), `model`, `effort`, `refusal_fallback`, `max_tokens`, `timeout_s`, `base_url`, `api_key_enc` (encrypted with `PGKILN_SECRET_KEY`, write-only), `enabled`. Not exported | no |
+| `ai_service` | [AI services](06-processing.md#generate-text-with-ai) of the installation: `name`, `provider` (`anthropic`, `openai`, `gemini`, `openai_compatible`: 121), `model`, `effort`, `refusal_fallback`, `max_tokens`, `timeout_s`, `base_url`, `api_key_enc` (encrypted with `PGKILN_SECRET_KEY`, write-only), `enabled`. Not exported | no |
 | `app_ai_service` | Which applications may use which AI service, with daily limits `max_requests` and `max_tokens` (null: no limit). Not exported | no (through `meta.ai_available`) |
 | `ai_usage` | One row per AI request: `at`, `app_id`, `page_no`, `username`, `service`, `provider`, `model`, `source`, `input_tokens`, `output_tokens`, `duration_ms`, `status`, `message` (an error class, never prompt or answer text). Not exported | no |
+| `ai_tool_call` | (121) Every tool call of an [AI assistant or agent](03-builder.md#ai-agents): `at`, `app_id`, `page_no`, `region_id`, `username`, `agent`, `tool`, `type`, `arguments` (the model's, cut to 4 KB), `status` (`ok`, `error`, `refused`), `duration_ms`, `message`. Kept 30 days, not exported | no |
 | `ai_conversation` | [AI assistant](04-pages-and-regions.md#ai_assistant-ai-assistant) conversations: one per session and region (`messages`: the provider's history, `turns`: what the page shows); deleted with the session. Not exported | no |
 | `ai_table_note` | Descriptions of tables and columns for models ([App Builder AI](03-builder.md#app-builder-ai)): `schema_name`, `table_name`, `column_name` (`''` for the table), `note`. Installation data, not exported | no |
 | `blueprint` | Saved [blueprints](03-builder.md#creating-an-application-from-a-blueprint): `name`, `spec` (the JSON), `app_id` (the application last created from it), `created_by`. Builder data, not exported | no |

package/docs/guide/11-from-apex.md

@@ -22,10 +22,11 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Instance administration: install/upgrade log | Workspace utilities → Installation (administrators) |
 | `APEX_WEB_SERVICE.make_rest_request`, `g_status_code` | `meta.web_request(url, method, body, headers, credential)` or `meta.web_request_source(source, params)`, then `meta.web_response(id)`. **Asynchronous**: the server makes the request after the page process that queued it, or after the commit ([chapter 9](09-reference.md#web-requests-from-sql)) |
 | Workspace → Generative AI services; *Generate Text with AI* process and dynamic action; `APEX_AI.generate` | Workspace utilities → AI services (Claude or OpenAI; administrators); the `ai_generate` process and dynamic action, with structured outputs into items ([chapter 6](06-processing.md#generate-text-with-ai)); `meta.ai_generate(service, prompt, system, schema)` then `meta.ai_result(id)` ([chapter 9](09-reference.md#ai-requests-from-sql)) |
-| AI Assistant region; AI agents with tools; natural language to interactive report (NL2IR) | The `ai_assistant` region: a chat with context queries (RAG over your queries) and tools (SQL as the app role with bound arguments, REST data sources) ([chapter 4](04-pages-and-regions.md#ai_assistant-ai-assistant)); `"ai_filter"` on a report: *Ask in your own words* ([chapter 4](04-pages-and-regions.md#natural-language-filters-ask-in-your-own-words)) |
+| AI Assistant region; AI agents with tools; AI interactive reports (natural language to interactive report) | The `ai_assistant` region: a chat with context queries (RAG over your queries) and tools (SQL as the app role with bound arguments, REST data sources) ([chapter 4](04-pages-and-regions.md#ai_assistant-ai-assistant)); `"ai_filter"` on a report: *Ask in your own words*, the request becomes the report's settings as editable chips, with or without an AI service ([chapter 4](04-pages-and-regions.md#ask-in-your-own-words-ai-interactive-reports)) |
 | App Builder / SQL Workshop AI Assistant (create pages, generate and explain SQL); describing tables for AI | The App Builder's AI service: *Create pages with AI* (proposals you confirm), SQL Workshop → AI (SQL from a question, shown not run; explain a query or error), *Describe tables* (`meta.ai_table_note`, optionally `COMMENT ON`) ([chapter 3](03-builder.md#app-builder-ai)) |
 | Blueprints (spec-driven development) | Create → From a blueprint: a JSON blueprint (tables, pages, menu, sample data), optionally drafted by AI, reviewed, then created in one transaction ([chapter 3](03-builder.md#creating-an-application-from-a-blueprint)) |
 | `APEX_DATA_PARSER.parse`, `get_columns` | `meta.parse_data(blob, …)` (rows with `cols` and `data`), `meta.parse_data_columns(blob, …)`; CSV/TSV and JSON, not Excel or XML ([chapter 9](09-reference.md#parsing-files-in-sql)) |
+| Team Development (issues, labels, milestones, templates, feedback) | Builder → Team Development (`/builder/team`): issues per workspace with labels in groups, milestones, assignees, application and page links, Markdown comments with @mentions shown in the builder, history, saved views and a board; a set-up wizard with sample labels, templates and milestones; feedback and developer comments become issues. No e-mail and no GitHub synchronisation ([chapter 3](03-builder.md#team-development)) |
 | Workspace users (APEX accounts), Application Access Control | `meta.account` (Builder → Users), `meta.app_access` (Access control) |
 | Page access protection "Arguments must have checksum" | `protection = 'checksum'` (the default) |
 | Automatic row processing (DML) | Process type `form_dml` |

package/docs/guide/12-development.md

@@ -33,6 +33,10 @@ src/
                            rows and columns from the response schema, write-back from collection and item paths, notes), catalog
                            files, load/insert/replace, sourceFromService
   workspace-export.ts      (sprint 67) a workspace's components as a file (pgkiln-workspace/1) and importWorkspace (one transaction)
+  team.ts                  (sprint 113) Team Development's data: workspaceDevelopers (members and administrators: assignees, @mentions),
+                           issueHtml (markdownHtml + mentions), recordMentions, logIssue (history), teamSetup, teamCounts, pageIssues,
+                           exportTeam / importTeam (the workspace export's "team" part)
+  team-samples.ts          (sprint 113) the set-up wizard's samples per builder language (English; add a key for another)
   subscriptions.ts         application types and subscriptions (migration 056): offers, subscribe, refresh, publish, in sync
   workingcopy.ts           working copies (migration 055): create, three-way compare per component (base, main, copy),
                            merge into the main application or refresh the copy, both through cli/replace.ts
@@ -55,7 +59,10 @@ src/
   customauth.ts            custom authentication: the app's function or PL/pgSQL body (a pg_temp function) and post-authentication code, as the app's role
   remember.ts              "Keep me signed in": rotating persistent sign-in tokens
   workflow.ts              workflows: step checks, the runner with parallel branches (NOTIFY + polling), invoke_api steps
-                           (the call between two transactions, with a lease), Advisor references, the diagram
+                           (the call between two transactions, with a lease), Advisor references, the diagram;
+                           (sprint 114) send_mail and draft steps, switch cases on task outcomes, the diagram as a standalone SVG
+  task-events.ts           (sprint 114) task events (complete, expire, fail: SQL, mail, start a workflow) and built-in task
+                           notifications from e-mail templates: checks, the actions as the app role, the meta.task_hook outbox runner
   process-jobs.ts          background execution chains: the job queue (SKIP LOCKED, NOTIFY + polling), running a job as the app role
   api.ts                   REST API tokens for PostgREST, API role checks
   accounts.ts              account settings and the password policy
@@ -138,7 +145,10 @@ src/
                            limits, the call, meta.ai_usage), requests.ts (meta.ai_generate from SQL: runPendingAi() after an sql
                            process, aiRequestTick() in the scheduler, 24-hour purge), chat.ts (conversations with tools, migration
                            061: chat() runs the tool loop on a provider-format history (Claude: streamed, strict tools, tool_choice
-                           auto, content appended unchanged; OpenAI: strict function tools), limits and usage per provider call)
+                           auto, content appended unchanged; OpenAI: strict function tools), limits and usage per provider call;
+                           (121) an agent's effort (Claude output_config.effort, OpenAI reasoning_effort) and output limit).
+                           Providers (121): anthropic, openai, gemini (OpenAI-compatible endpoint, GEMINI_BASE_URL), openai_compatible
+                           (Ollama, vLLM, Azure OpenAI; base URL required, key optional): service.ts serviceKey(), baseUrlFor(), providerLabel()
   debug.ts                 debug messages: DebugLog (levels, timed steps, NOTICEs of meta.debug from appTx), started in
                            loadContext, stored after the response (onResponse hook → meta.debug_save), hourly purge
   icons.ts                 icon helper (sprite in public/icons.svg)
@@ -156,7 +166,7 @@ src/
     styles.ts              base styles (BASE_STYLES: Iris, Lavender, Standard; baseStyleOf → html data-style), Theme Roller style variants: fixed lists (fonts, sizes, corners), parseStyle/appStyles checks, the request's
                            style (user choice, default), themeCss() (only hex values and constants reach the CSS)
     template-options.ts    template options: the fixed CSS class list per region and button, templateClasses() (unknown values ignored)
-    regions.ts             region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges)
+    regions.ts             region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges; (124) menu entries {action} → data-menu-entry for menu_entry dynamic actions)
     report.ts, report-views.ts (group by, pivot, chart), compute.ts (computed column expressions), grid.ts (aggregates, row actions, Actions menu, single row view, layoutFromForm), grid-layout.ts (column layouts: clean, arrange, per user), master-detail.ts (signed master row selection, details), facets.ts (facetChart: a facet's counts as a chart, sprint 65), items.ts
                            (report.ts: paging with row ranges and max_rows, keyset paging (keysetPlan, seekCondition, signed r<id>_k), pagerNav, streamed CSV/Excel downloads with a cursor;
                            items.ts: lovOptions, searchLov/lovLookup for popup LOVs, served by POST /a/:alias/:page/lov/:item/search in routes.ts)
@@ -193,7 +203,8 @@ src/
     template-components.ts template components: template language (allow-list, directives, escaping), plug-in files, report column templates
     builtin-components.ts  built-in template components (ut_avatar, ut_badge, ut_comments, ut_media_list, ut_metric_card, ut_timeline)
     template-region.ts     template_component region
-    tasks.ts               task list region and task actions (approvals); (094) the vacation rule panel and route
+    tasks.ts               task list region and task actions (approvals); (094) the vacation rule panel and route;
+                           (sprint 114) custom outcome buttons, the Fail event and recovery of a failing completion SQL
     data-reporter.ts       Data Reporter region (migration 057): sources from the region's config, checkDef (offered columns, whitelists),
                            reportQuery/chartQuery, the list and editor (GET form), save/delete routes (meta.save_data_report);
                            (sprint 110) dataset sources (resolveSources), edit_authz / admin_authz / publishing, pins (a preference),
@@ -205,8 +216,20 @@ src/
                            schemas from items, answers into items), aiInputs/aiOutputs for its dynamic action (route in routes.ts)
     assistant.ts           AI assistant region (migration 061): config checks, tool schemas and argument checks, context queries
                            and SQL tools as the app role (rolled back unless "writes"), REST tools, meta.ai_conversation per
-                           session, formatAnswer (escaped), send/clear routes
-    ai-filter.ts           natural-language filters on a report ("ai_filter"): columns → structured output → checked → r<id>_f/q/s/d
+                           session, formatAnswer (escaped), send/clear routes; (121) "agent": an AI agent's service, prompt, tools,
+                           steps and authorization; links of navigate tools under the answer, browser actions once (__AIACT<id>)
+    ai-agents.ts           (121) AI agents and AI tools (meta.app.ai_agents / ai_tools): checks (agentProblems, aiToolProblems,
+                           definitionProblems), agentFor(), prepareTools() (authorization schemes, navigate pages the user may
+                           open, strict schemas), runAgentTool() (sql: read-only transaction as the app role with a time limit;
+                           function: named arguments, committed; rest; javascript: queued for the browser; navigate: URL and
+                           checksum built here), logToolCall() (meta.ai_tool_call, debug level 4, 30-day purge)
+    ai-filter.ts           "Ask in your own words" on a report ("ai_filter", sprint 112: AI interactive reports): the box, the chips
+                           form (Edit/Remove/Undo, undo history in the session), ask and chips routes; an AI service's structured
+                           output (planSchema) or the phrase parser, then ir-plan.ts
+    ir-plan.ts             what a question may set: checkPlan (shown columns, whitelists, computeSql), applyPlan (→ the report's
+                           URL parameters), chipsOf/editChip/removeChip (a chip = one URL parameter value, edits checked again)
+    ir-phrases.ts          the rule-based parser without an AI service: phrase tables per language (en, nl, de), clauses →
+                           a RawPlan; values looked up among the report's rows through a Lookup (query parameter)
     pdf.ts                 report PDFs with report layouts (pdfkit); rows from a cursor in batches (tablePdf takes batches)
     search.ts              search region and search configurations (migration 080): words as ILIKE parameters, table/sql/list
                            sources as the app role in savepoints, marked results, configColumns/searchConfigProblems for the Advisor
@@ -256,6 +279,11 @@ src/
     availability.ts        Application → Availability (migration 083): status, message, users, build status (Run only is
                            enforced by locks.ts blockingLock); availabilityBadge() in the application header
     feedback.ts            Application → Feedback (migration 084): the setting, the list with filters, status and answers
+    team.ts                (sprint 113, migration 122) Builder → Team Development /builder/team: issues (list with filters and saved views,
+                           board by label group or milestone with a Move form per card, issue page with Markdown, comments, canned
+                           responses, @mentions, history), labels and groups, milestones, templates, the set-up wizard; Make an issue
+                           from feedback and developer comments; pageIssuesNote (Page Designer), appIssues (App Home), teamHomeBlock
+                           (Workspace home). Every id from a request is looked up in the current workspace
     region-help.ts         the Attributes (JSON) help per region type, with links to the guide
     mail.ts                Workspace utilities → Mail services (administrators: providers, write-only secret, allowed senders,
                            applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel)
@@ -337,6 +365,8 @@ src/
                            workspace's applications, the module › template › handler tree, handler forms, Try it (inject with a
                            short-lived token), Run only / lock checks
     workflows.ts           workflow versions, diagram and instances (Shared Components)
+    workflow-migrate.ts    (sprint 114) migrating running workflow instances to a newer version (map, preview, apply with
+                           meta.migrate_workflows) and the diagram as an SVG file (PNG in builder.js)
     process-jobs.ts        page designer: the Jobs tab of a background chain process
     template-spec.ts       template component property form (Shared Components)
     websources.ts          web credentials and REST data sources: property specs, secret status, Test, suggested columns,
@@ -359,13 +389,17 @@ src/
     ai-builder.ts          App Builder AI (migration 062): the builder's AI service (meta.builder_ai), SQL Workshop → AI (SQL from a
                            question, shown not run; explain), describe tables (meta.ai_table_note, COMMENT ON, AI drafts),
                            create pages with AI (proposals checked by checkProposals, created with meta.generate_page)
-    assistant.ts           page designer: AI assistant settings and a report's "Ask in your own words" (AI service, placeholder)
+    assistant.ts           page designer: AI assistant settings and a report's "Ask in your own words" (off, built-in phrases or an AI service, placeholder)
     ai.ts                  Workspace utilities → AI services (administrators: services, write-only encrypted keys, access and
                            daily limits per app, Test, usage log) and Activity → AI usage per application
+    ai-agents.ts           (121) Shared Components → AI Agents: the agent and tool forms (checked before saving, renames follow
+                           into agents and regions), toolCallTable() (Activity → AI usage → Tool calls), agentOptions()
     supporting.ts          supporting objects: review page, running the install/upgrade/deinstall scripts as the app's role in one transaction
 public/
   app.css                  theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*)
-  app.js                   client runtime: dialogs (dialog_closed actions), popup LOVs, dynamic actions (focus, classes, messages), grids (add/duplicate rows, master-detail refresh, move/resize columns, copy/paste of cell ranges), menus, lazy regions, maps (Leaflet layers, marker clusters, heat layer, layer legend, area/distance filter) (no inline JS)
+  app.js                   client runtime: dialogs (dialog_closed actions), popup LOVs (sprint 115: the next page loads on scroll through an
+                           IntersectionObserver, ‹/More without one), dynamic actions (focus, classes, messages; sprint 115: wait_popup /
+                           remove_wait_popup as a modal <dialog class="wait-popup">, pgkiln.waitPopup(), the menu_entry event), grids (add/duplicate rows, master-detail refresh, move/resize columns, copy/paste of cell ranges), menus, lazy regions, maps (Leaflet layers, marker clusters, heat layer, layer legend, area/distance filter) (no inline JS)
   code-editor.js, .css     builder code editor: enhances <textarea data-code>, highlighting, suggestions (no dependencies);
                            (sprint 108) the current line, and read-only <pre data-code-view="sql|plpgsql|json|html"> highlighted;
                            its colours are the --ce-* tokens in builder.css
@@ -426,6 +460,8 @@ test/
   rest-sources.test.ts     REST data sources, web credentials, SSRF checks, invoke_api (mock service + HR page 23)
   rest-modules.test.ts     (sprint 104) modules, templates, PL/pgSQL and media handlers, OpenAPI, the builder's tree and Try it
   workflow-invoke.test.ts  workflow invoke_api steps: the call between transactions, faults, retry, lease, Advisor, export (mock service)
+  workflow-outcomes.test.ts (sprint 114) custom task outcomes, task events and notifications, fail recovery, send_mail and draft
+                           steps, migrating running instances, the SVG export (HR part 67: SALARY_CHANGE)
   large-tables.test.ts     row ranges, max_rows, row limits, lazy regions, region caching, streamed downloads (HR page 25)
   grid.test.ts             interactive grid: aggregates, layouts per user, saved grid reports, master-detail, row actions (HR page 27)
   custom-auth.test.ts      custom authentication: function body, named function, post-authentication code, builder settings

package/docs/guide/20-ai-agents.md

@@ -7,8 +7,10 @@ it exports the application as files, edits them with its own file tools, shows t
 and imports them again. Laravel developers know the idea from Laravel Boost.
 
 This is separate from the AI features *inside* applications and the builder (AI assistant regions,
-*Generate with AI*): those call a model from pgkiln; here an agent on the developer's machine calls
-pgkiln.
+[AI agents with tools](03-builder.md#ai-agents) in Shared Components, *Generate with AI*): those call a
+model from pgkiln; here an agent on the developer's machine calls pgkiln. An application's AI agents
+and tools are part of its files (`app.json`: `ai_agents`, `ai_tools`), so a coding agent can read and
+change them like any other component.
 
 ## Setting it up
 

package/examples/hr/README.md

@@ -40,6 +40,8 @@ Then open http://127.0.0.1:3100/a/hr and sign in as `king`, `blake`, `jones`, `a
 | `hr_47_plugins.sql` | *Plug-ins* (page 40): the four example plug-ins of `examples/plugins/` (a region, an item, a dynamic action and a process plug-in) |
 | `hr_48_map_tiles.sql` | *Weather stations* (page 41): 20,000 generated stations (`hr.weather_station`) as vector tiles, and the stations above 2,000 m loaded for the visible area |
 | `hr_49_push_notifications.sql` | Push notifications: the app may send them (users turn them on under *My account → Notifications*); a new leave request notifies the manager, a decision notifies the employee, and the notification opens the request (page 7) |
+| `hr_64_ai_agent.sql` | *HR agent* (page 46): the AI agent `HR_AGENT` (Shared Components → AI Agents) with four tools: `top_earners` (SQL, read-only as `hr_app`), `open_employee` (navigate: a link to the employee form with its checksum, only for users who may open page 3), `give_raise` (the PL/pgSQL function `hr.give_raise`, managers only) and `note` (a JavaScript tool: the custom event `hr_agent_note`). Ask *Who in Sales earns most?* Needs an AI service named `HR_ASSISTANT` (see part 41) |
+| `hr_68_component_details.sql` | *Component details* (page 47): a popup LOV over 6,000 rows that loads more as the dialog scrolls, a wait popup around a two-second process (*Recalculate*) and around an Ajax call (*Check in the background*), and an *Actions* menu whose entries run dynamic actions (event `menu_entry`) |
 
 The files run in order, each once (recorded in `public.pgkiln_seed`), so new ones can be added
 later. pgkiln's own tests use this application as their fixture (`npm test` installs it first).

package/examples/hr/hr_64_ai_agent.sql

@@ -0,0 +1,97 @@
+-- =====================================================================
+-- HR example, part 64: an AI agent with tools (sprint 111;
+-- docs/guide/03-builder.md, "AI agents"; APEX 26.1: AI Agents)
+--
+-- Shared Components → AI Agents:
+--   - Tools:
+--       top_earners    (sql)        employees by salary, highest first,
+--                                   optionally of one department: a query
+--                                   run as hr_app (row level security
+--                                   applies) in a read-only transaction
+--       open_employee  (navigate)   a link to the employee form (page 3)
+--                                   with P3_EMPNO: pgkiln offers it only
+--                                   to users who may open page 3
+--                                   (MANAGER) and builds the checksum
+--       give_raise     (function)   hr.give_raise(p_empno, p_pct): changes
+--                                   data, only offered to managers
+--       note           (javascript) shows a message in the browser after
+--                                   the answer (the custom event
+--                                   "hr_agent_note" on page 46)
+--   - Agent HR_AGENT: the AI service HR_ASSISTANT, a system prompt, low
+--     reasoning effort, the four tools, at most 4 steps per question.
+--
+-- Page 46 "HR agent": an AI assistant region that names the agent. Ask
+-- e.g. "Who in Sales earns most?": the agent calls top_earners and offers
+-- "Open BLAKE's record", a link to page 3 with a valid checksum.
+--
+-- Like parts 41 and 42 the example creates no AI service: an administrator
+-- adds one named HR_ASSISTANT under App Builder → Workspace utilities → AI
+-- services (Claude, OpenAI, Gemini or an OpenAI-compatible endpoint) and
+-- allows the HR application to use it.
+-- =====================================================================
+
+update meta.app set
+  ai_tools = $j$[
+    {"name": "top_earners", "type": "sql",
+     "description": "Active employees with their job, department and salary, highest salary first; optionally only one department (case-insensitive name, e.g. SALES).",
+     "sql": "select empno, ename, job, dname, sal from hr.staff_v where active and (:DNAME is null or dname ilike :DNAME) order by sal desc, ename",
+     "parameters": {"DNAME": {"type": "string", "optional": true, "description": "A department name, e.g. SALES."}},
+     "max_rows": 20, "timeout_s": 10},
+    {"name": "open_employee", "type": "navigate",
+     "description": "Offer the user a link to an employee's record (the employee form). Use the employee number (empno) as P3_EMPNO and a label such as \"Open BLAKE's record\".",
+     "pages": [3]},
+    {"name": "give_raise", "type": "function",
+     "description": "Raise an employee's salary by a percentage. Only when the user clearly asks for it; repeat the employee and the percentage first.",
+     "function": "hr.give_raise",
+     "parameters": {"P_EMPNO": {"type": "integer", "description": "The employee number (empno)."},
+                    "P_PCT": {"type": "number", "description": "The raise in percent, e.g. 5."}},
+     "authz": "MANAGER"},
+    {"name": "note", "type": "javascript", "action": "hr_agent_note",
+     "description": "Show the user a short confirmation message in the page, e.g. after a raise.",
+     "parameters": {"TEXT": {"type": "string", "description": "The message."}}}
+  ]$j$::jsonb,
+  ai_agents = $j$[
+    {"name": "HR_AGENT", "description": "Answers questions about salaries and opens employee records",
+     "service": "HR_ASSISTANT",
+     "system": "You are the HR agent of a small company, talking with &APP_USER.. Answer questions about employees, departments and salaries with the top_earners tool. When you name one employee, offer a link to their record with open_employee (the empno as P3_EMPNO). Be brief.",
+     "effort": "low", "tools": ["top_earners", "open_employee", "give_raise", "note"], "max_steps": 4, "max_tokens": 2000}
+  ]$j$::jsonb
+ where alias = 'hr';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select id, 46, 'HR agent', 'HR agent', 1 from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, template, source, condition, config)
+select p.id, r.seq, r.title, r.type, r.cols, 'standard', r.source, r.cond, r.config::jsonb
+  from meta.page p join meta.app a on a.id = p.app_id, (values
+  (10, 'No AI service yet', 'static', 12,
+   '<p class="alert alert-info">No AI service is configured for this application yet. An administrator adds an AI service named <b>HR_ASSISTANT</b> under <i>App Builder → Workspace utilities → AI services</i> and allows the HR application to use it.</p>',
+   'not meta.ai_available(''HR_ASSISTANT'')', '{}'),
+  (20, 'Ask the HR agent', 'ai_assistant', 8, null, 'meta.ai_available(''HR_ASSISTANT'')',
+   $j${"agent": "HR_AGENT",
+       "welcome": "Hello! Ask me who earns what, e.g. who in Sales earns most. I can open an employee's record for you.",
+       "placeholder": "e.g. Who in Sales earns most?",
+       "max_turns": 20,
+       "error_message": "The HR agent could not answer just now. Please try again later."}$j$)
+  ) as r (seq, title, type, cols, source, cond, config)
+ where a.alias = 'hr' and p.page_no = 46;
+
+-- the javascript tool "note": a custom event the agent raises after its answer
+insert into meta.dynamic_action (page_id, seq, name, event, trigger_element, action, message)
+select p.id, 10, 'Agent note', 'custom', 'hr_agent_note', 'show_success', 'The HR agent did what you asked.'
+  from meta.page p join meta.app a on a.id = p.app_id where a.alias = 'hr' and p.page_no = 46;
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select id, 30, 'HR agent', 'users', 46 from meta.app where alias = 'hr';
+
+insert into meta.translation (app_id, language, source, target)
+select a.id, 'nl', t.source, t.target
+  from meta.app a, (values
+  ('HR agent', 'HR-agent'),
+  ('Ask the HR agent', 'Vraag het de HR-agent'),
+  ('Hello! Ask me who earns what, e.g. who in Sales earns most. I can open an employee''s record for you.',
+   'Hallo! Vraag me wie wat verdient, bijv. wie in Sales het meest verdient. Ik kan ook de gegevens van een medewerker voor je openen.'),
+  ('e.g. Who in Sales earns most?', 'bijv. Wie verdient het meest in Sales?')
+  ) as t (source, target)
+ where a.alias = 'hr'
+on conflict do nothing;

package/examples/hr/hr_65_ask_reports.sql

@@ -0,0 +1,21 @@
+-- =====================================================================
+-- HR example, part 65: "Ask in your own words" without an AI service
+-- (docs/guide/04-pages-and-regions.md, "Ask in your own words")
+--
+-- Page 2 "Employees": the interactive report gets a question box with the
+-- built-in phrases ("ai_filter": {} names no AI service). Try
+--   sum of salary by department where job is clerk
+--   salary over 2500, sort by hire date, newest first
+--   only clerks hired after 1981
+--   bonus is 10% of salary
+--   highlight salary over 4000 in red
+-- Each answer becomes the report's own settings (filters, sort, group by,
+-- computed columns, …), shown as chips with Edit and Remove under the box;
+-- Undo goes back a step. Page 38's staff list uses the HR_ASSISTANT AI
+-- service when an administrator has added it, else the same phrases.
+-- =====================================================================
+
+update meta.region r
+   set config = r.config || '{"ai_filter": {"placeholder": "e.g. sum of salary by department where job is clerk"}}'
+  from meta.page p, meta.app a
+ where r.page_id = p.id and p.app_id = a.id and a.alias = 'hr' and p.page_no = 2 and r.type = 'report';

package/examples/hr/hr_66_team_development.sql

@@ -0,0 +1,58 @@
+-- =====================================================================
+-- HR example, part 66: Team Development (docs/guide/03-builder.md,
+-- "Team Development")
+--
+-- What Builder → Team Development → Set up installs in the Default
+-- workspace (the label groups Type and Priority, milestones 1.0 and 1.1,
+-- a bug report template and a canned response), and one issue about the
+-- HR application: "Salary rounding on page 12", a Bug of milestone 1.1,
+-- assigned to admin. The Page Designer of page 12 shows it, and the
+-- Workspace home counts it until it is closed. Issues are workspace data
+-- (the workspace export), not part of the HR application's export.
+-- =====================================================================
+
+insert into meta.team_label_group (workspace_id, name, description, seq) values
+  (1, 'Type', 'What kind of work the issue is.', 10),
+  (1, 'Priority', 'How soon it should be done.', 20)
+on conflict (workspace_id, lower(name)) do nothing;
+
+insert into meta.team_label (workspace_id, group_id, name, color, description, seq)
+select 1, g.id, l.name, l.color, l.description, l.seq
+  from (values ('Type', 'Bug', 'red', 'Something does not work as it should.', 10),
+               ('Type', 'Feature', 'blue', 'New functionality.', 20),
+               ('Type', 'Task', 'teal', 'Work to do that is neither a bug nor a feature.', 30),
+               ('Priority', 'High', 'orange', 'Do this first.', 10),
+               ('Priority', 'Medium', 'yellow', 'Do this soon.', 20),
+               ('Priority', 'Low', 'gray', 'Do this when there is time.', 30)) as l(grp, name, color, description, seq)
+  join meta.team_label_group g on g.workspace_id = 1 and g.name = l.grp
+on conflict (workspace_id, lower(name)) do nothing;
+
+insert into meta.team_milestone (workspace_id, name, description, due_date) values
+  (1, '1.0', 'The first release.', current_date + 30),
+  (1, '1.1', 'The first update after the release.', current_date + 90)
+on conflict (workspace_id, lower(name)) do nothing;
+
+insert into meta.team_template (workspace_id, kind, name, title, body, labels, seq) values
+  (1, 'issue', 'Bug report', 'Bug: ', E'## What happens\n\n\n## What should happen\n\n\n## Steps to reproduce\n\n1. \n2. \n', '{Bug}', 10),
+  (1, 'response', 'Thanks, we will look at it', null, 'Thank you for reporting this. We will look at it and keep this issue up to date.', '{}', 10)
+on conflict (workspace_id, kind, lower(name)) do nothing;
+
+with issue as (
+  insert into meta.team_issue (workspace_id, title, body, milestone_id, app_id, page_no, created_by)
+  select 1, 'Salary rounding on page 12',
+         E'The leave calendar shows daily salary costs rounded to whole euros; finance expects cents.\n\n'
+         || E'- Open **page 12** (Leave calendar)\n- Compare a day with the salary in `hr.emp`\n\n@admin can you have a look?',
+         (select id from meta.team_milestone where workspace_id = 1 and name = '1.1'),
+         a.id, 12, 'admin'
+    from meta.app a
+   where a.alias = 'hr'
+     and not exists (select 1 from meta.team_issue i where i.workspace_id = 1 and i.title = 'Salary rounding on page 12')
+  returning id
+), labelled as (
+  insert into meta.team_issue_label (issue_id, label_id)
+  select issue.id, l.id from issue join meta.team_label l on l.workspace_id = 1 and l.name in ('Bug', 'Medium')
+), assigned as (
+  insert into meta.team_issue_assignee (issue_id, username)
+  select issue.id, 'admin' from issue where exists (select 1 from meta.developer where username = 'admin')
+)
+insert into meta.team_issue_event (issue_id, username, action) select id, 'admin', 'created' from issue;

package/examples/hr/hr_67_workflow_outcomes.sql

@@ -0,0 +1,113 @@
+-- =====================================================================
+-- HR example, part 67: custom task outcomes, task events and
+-- notifications, a Send E-Mail step, drafts and versions of a workflow
+-- (migration 123; docs/guide/06-processing.md, "Approvals" and "Workflows")
+--
+-- SALARY_DECISION is a task with three outcomes instead of Approve / Reject:
+-- Yes, No and Undecided. Its owners (role admin) get an e-mail when a task
+-- is created (notification SALARY_TASK); when one is completed an event
+-- records the decision as a notification for the initiator.
+--
+-- SALARY_CHANGE asks for that decision and branches on its outcome:
+--   1. APPROVE  the task (an administrator decides)
+--   2. DECIDE   YES: apply the new salary; UNDECIDED: ask again; otherwise the end
+--   3. APPLY    the new salary (SQL)
+--   4. TELL     an e-mail to the employee (version 2: a send_mail step)
+-- Version 1 had no TELL step and is inactive; version 2 is active; version 3
+-- is in development with a draft step (BUDGET_CHECK) that is still a
+-- placeholder: it is drawn dashed, and can't be activated until it is
+-- replaced. Instances of version 1 can be migrated to version 2 under
+-- Shared Components → Workflows → SALARY_CHANGE → Migrate running instances.
+--
+-- Start one from SQL (e.g. the SQL Workshop, signed in to the application):
+--   select meta.start_workflow('SALARY_CHANGE', '7499', '{"ENAME": "Allen", "NEW_SAL": 1760}')
+-- and decide on it under My tasks (page 14) as king.
+-- =====================================================================
+
+insert into meta.email_template (app_id, name, subject, html_body, text_body)
+select id, 'SALARY_TASK', 'To decide: #SUBJECT#',
+$h$<p>A salary change waits for your decision: <b>#SUBJECT#</b>.</p>
+<p>Requested by #INITIATOR#. Decide under <i>My tasks</i> in HR Demo.</p>$h$,
+$t$A salary change waits for your decision: #SUBJECT#.
+
+Requested by #INITIATOR#. Decide under "My tasks" in HR Demo.$t$
+  from meta.app where alias = 'hr'
+union all
+select id, 'SALARY_CHANGED', 'Your salary changes to #NEW_SAL#',
+$h$<p>Dear #ENAME#,</p><p>Your new salary of <b>#NEW_SAL#</b> was approved by #TASK_APPROVER#.</p><p>Kind regards,<br>HR</p>$h$,
+$t$Dear #ENAME#,
+
+Your new salary of #NEW_SAL# was approved by #TASK_APPROVER#.
+
+Kind regards,
+HR$t$
+  from meta.app where alias = 'hr';
+
+insert into meta.task_definition (app_id, name, type, subject, owner_roles, admin_role, priority, due_in, outcomes, events, notifications)
+select id, 'SALARY_DECISION', 'approval', 'Salary of &ENAME. to &NEW_SAL.', '{admin}'::text[], 'admin', 2, '5 days',
+       $o$[{"name": "YES", "label": "Yes", "colour": "success"},
+           {"name": "NO", "label": "No", "colour": "danger"},
+           {"name": "UNDECIDED", "label": "Undecided", "colour": "warning"}]$o$::jsonb,
+       $e$[{"on": "complete", "type": "sql", "code": "select hr.salary_decided(:DETAIL_PK::int, :OUTCOME, :INITIATOR)"}]$e$::jsonb,
+       '{"create": "SALARY_TASK"}'::jsonb
+  from meta.app where alias = 'hr';
+
+-- Notifications are for other users, which RLS forbids the app: security definer, like the onboarding ones.
+create function hr.salary_decided(p_empno int, p_outcome text, p_initiator text) returns void
+language plpgsql security definer set search_path = hr, pg_catalog as $$
+begin
+  insert into hr.notification (username, message)
+  select p_initiator, format('Salary change of %s: %s.', initcap(e.ename), lower(p_outcome))
+    from hr.emp e where e.empno = p_empno;
+end
+$$;
+create function hr.salary_change_apply(p_empno int, p_sal numeric) returns timestamptz
+language plpgsql security definer set search_path = hr, pg_catalog as $$
+begin
+  if p_sal is null or p_sal <= 0 then
+    raise exception 'A salary is more than 0.';
+  end if;
+  update hr.emp set sal = p_sal where empno = p_empno;
+  return now();
+end
+$$;
+-- the e-mail address of an employee's account (the accounts are pgkiln's, not the application's)
+create function hr.employee_email(p_empno int) returns text
+language sql stable security definer set search_path = hr, pg_catalog as $$
+  select a.email from hr.emp e join meta.account a on lower(a.username) = lower(e.username) where e.empno = p_empno and a.active
+$$;
+revoke all on function hr.salary_decided(int, text, text), hr.salary_change_apply(int, numeric), hr.employee_email(int) from public;
+grant execute on function hr.salary_decided(int, text, text), hr.salary_change_apply(int, numeric), hr.employee_email(int) to hr_app;
+
+-- version 1, then version 2 (with the e-mail) becomes active, then version 3 in development (a draft step)
+insert into meta.workflow_definition (app_id, name, title, description, admin_role, steps)
+select id, 'SALARY_CHANGE', 'Salary of &ENAME. to &NEW_SAL.', 'A salary change, decided by an administrator (Yes, No or Undecided).', 'admin',
+$s$[
+  {"name": "APPROVE", "type": "task", "task": "SALARY_DECISION"},
+  {"name": "DECIDE", "type": "switch", "cases": [{"outcome": "YES", "next": "APPLY"}, {"outcome": "UNDECIDED", "next": "APPROVE"}], "otherwise": "END"},
+  {"name": "APPLY", "type": "sql", "code": "select hr.salary_change_apply(:DETAIL_PK::int, :NEW_SAL::numeric) as applied_at", "next": "END"},
+  {"name": "END", "type": "end"}
+]$s$::jsonb
+  from meta.app where alias = 'hr';
+
+select meta.new_workflow_version(d.id) from meta.workflow_definition d join meta.app a on a.id = d.app_id where a.alias = 'hr' and d.name = 'SALARY_CHANGE';
+update meta.workflow_definition d set dev_steps = $s$[
+  {"name": "APPROVE", "type": "task", "task": "SALARY_DECISION"},
+  {"name": "DECIDE", "type": "switch", "cases": [{"outcome": "YES", "next": "APPLY"}, {"outcome": "UNDECIDED", "next": "APPROVE"}], "otherwise": "END"},
+  {"name": "APPLY", "type": "sql", "code": "select hr.salary_change_apply(:DETAIL_PK::int, :NEW_SAL::numeric) as applied_at"},
+  {"name": "TELL", "type": "send_mail", "to": "select hr.employee_email(:DETAIL_PK::int)", "template": "SALARY_CHANGED", "next": "END"},
+  {"name": "END", "type": "end"}
+]$s$::jsonb
+  from meta.app a where a.id = d.app_id and a.alias = 'hr' and d.name = 'SALARY_CHANGE';
+select meta.activate_workflow_version(d.id) from meta.workflow_definition d join meta.app a on a.id = d.app_id where a.alias = 'hr' and d.name = 'SALARY_CHANGE';
+
+select meta.new_workflow_version(d.id) from meta.workflow_definition d join meta.app a on a.id = d.app_id where a.alias = 'hr' and d.name = 'SALARY_CHANGE';
+update meta.workflow_definition d set dev_steps = $s$[
+  {"name": "BUDGET_CHECK", "type": "draft", "note": "check the department's budget", "next": "APPROVE"},
+  {"name": "APPROVE", "type": "task", "task": "SALARY_DECISION"},
+  {"name": "DECIDE", "type": "switch", "cases": [{"outcome": "YES", "next": "APPLY"}, {"outcome": "UNDECIDED", "next": "APPROVE"}], "otherwise": "END"},
+  {"name": "APPLY", "type": "sql", "code": "select hr.salary_change_apply(:DETAIL_PK::int, :NEW_SAL::numeric) as applied_at"},
+  {"name": "TELL", "type": "send_mail", "to": "select hr.employee_email(:DETAIL_PK::int)", "template": "SALARY_CHANGED", "next": "END"},
+  {"name": "END", "type": "end"}
+]$s$::jsonb
+  from meta.app a where a.id = d.app_id and a.alias = 'hr' and d.name = 'SALARY_CHANGE';