pgkiln 0.51.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/README.md +1 -1
  2. package/SECURITY.md +10 -1
  3. package/db/migrations/121_ai_agents.sql +94 -0
  4. package/db/migrations/122_team_development.sql +186 -0
  5. package/db/migrations/123_workflow_outcomes.sql +407 -0
  6. package/db/migrations/124_component_details.sql +51 -0
  7. package/db/migrations/125_app_change.sql +23 -0
  8. package/db/migrations/126_mail_queue_network_access.sql +119 -0
  9. package/docs/apex-feature-parity.md +50 -19
  10. package/docs/guide/01-installation.md +8 -4
  11. package/docs/guide/03-builder.md +197 -10
  12. package/docs/guide/04-pages-and-regions.md +71 -21
  13. package/docs/guide/05-items.md +7 -1
  14. package/docs/guide/06-processing.md +129 -9
  15. package/docs/guide/07-dynamic-actions.md +34 -0
  16. package/docs/guide/08-security.md +55 -0
  17. package/docs/guide/09-reference.md +5 -2
  18. package/docs/guide/11-from-apex.md +3 -1
  19. package/docs/guide/12-development.md +87 -16
  20. package/docs/guide/14-globalization.md +49 -1
  21. package/docs/guide/18-cli.md +21 -1
  22. package/docs/guide/19-rest-data-sources.md +12 -0
  23. package/docs/guide/20-ai-agents.md +12 -4
  24. package/examples/hr/README.md +2 -0
  25. package/examples/hr/hr_64_ai_agent.sql +97 -0
  26. package/examples/hr/hr_65_ask_reports.sql +21 -0
  27. package/examples/hr/hr_66_team_development.sql +58 -0
  28. package/examples/hr/hr_67_workflow_outcomes.sql +113 -0
  29. package/examples/hr/hr_68_component_details.sql +96 -0
  30. package/examples/hr/hr_70_data_security.sql +79 -0
  31. package/package.json +1 -1
  32. package/public/app.css +135 -21
  33. package/public/app.js +134 -20
  34. package/public/builder.css +133 -1
  35. package/public/builder.js +51 -0
  36. package/src/ai/chat.ts +18 -18
  37. package/src/ai/service.ts +35 -11
  38. package/src/ai/types.ts +7 -2
  39. package/src/app.ts +15 -0
  40. package/src/builder/advisor.ts +6 -3
  41. package/src/builder/ai-agents.ts +372 -0
  42. package/src/builder/ai-builder.ts +3 -3
  43. package/src/builder/ai.ts +13 -9
  44. package/src/builder/app-updates.ts +55 -0
  45. package/src/builder/assistant.ts +22 -7
  46. package/src/builder/components.ts +38 -9
  47. package/src/builder/data-security.ts +182 -0
  48. package/src/builder/designer.ts +8 -3
  49. package/src/builder/feedback.ts +6 -1
  50. package/src/builder/home.ts +16 -5
  51. package/src/builder/locks.ts +7 -1
  52. package/src/builder/mail-queue.ts +212 -0
  53. package/src/builder/mail.ts +72 -45
  54. package/src/builder/network-access.ts +140 -0
  55. package/src/builder/object-actions.ts +1 -0
  56. package/src/builder/object-browser.ts +1 -1
  57. package/src/builder/region-help.ts +2 -2
  58. package/src/builder/rest-catalogs.ts +19 -4
  59. package/src/builder/routes.ts +4 -1
  60. package/src/builder/shared.ts +1 -1
  61. package/src/builder/sql.ts +2 -0
  62. package/src/builder/team.ts +991 -0
  63. package/src/builder/themeroller.ts +47 -6
  64. package/src/builder/ui.ts +7 -1
  65. package/src/builder/websources.ts +1 -1
  66. package/src/builder/workflow-migrate.ts +210 -0
  67. package/src/builder/workflows.ts +29 -6
  68. package/src/builder/workspace-home.ts +2 -0
  69. package/src/builder/workspace-mail.ts +121 -0
  70. package/src/builder/workspace-transfer.ts +1 -1
  71. package/src/builder/workspaces.ts +1 -0
  72. package/src/cli/main.ts +25 -3
  73. package/src/cli/mcp.ts +40 -4
  74. package/src/cli/only.ts +52 -0
  75. package/src/cli/replace.ts +11 -1
  76. package/src/datasec.ts +343 -0
  77. package/src/i18n/ar.ts +17 -0
  78. package/src/i18n/cs.ts +17 -0
  79. package/src/i18n/da.ts +17 -0
  80. package/src/i18n/de.ts +17 -0
  81. package/src/i18n/el.ts +17 -0
  82. package/src/i18n/es.ts +17 -0
  83. package/src/i18n/fi.ts +17 -0
  84. package/src/i18n/fr.ts +17 -0
  85. package/src/i18n/he.ts +17 -0
  86. package/src/i18n/it.ts +17 -0
  87. package/src/i18n/ja.ts +17 -0
  88. package/src/i18n/ko.ts +17 -0
  89. package/src/i18n/nb.ts +17 -0
  90. package/src/i18n/pl.ts +17 -0
  91. package/src/i18n/pt.ts +17 -0
  92. package/src/i18n/ru.ts +17 -0
  93. package/src/i18n/sv.ts +17 -0
  94. package/src/i18n/tr.ts +17 -0
  95. package/src/i18n/uk.ts +17 -0
  96. package/src/i18n/zh.ts +17 -0
  97. package/src/i18n.ts +34 -0
  98. package/src/instance.ts +2 -0
  99. package/src/mail/mail.ts +50 -11
  100. package/src/mail/providers.ts +6 -3
  101. package/src/metadata.ts +11 -3
  102. package/src/network-acl.ts +126 -0
  103. package/src/objectstore.ts +3 -0
  104. package/src/runtime/ai-agents.ts +365 -0
  105. package/src/runtime/ai-filter.ts +385 -107
  106. package/src/runtime/assistant.ts +64 -11
  107. package/src/runtime/context.ts +2 -0
  108. package/src/runtime/engine.ts +3 -1
  109. package/src/runtime/ir-phrases.ts +812 -0
  110. package/src/runtime/ir-plan.ts +449 -0
  111. package/src/runtime/items.ts +1 -1
  112. package/src/runtime/regions.ts +6 -2
  113. package/src/runtime/render.ts +5 -3
  114. package/src/runtime/report.ts +1 -1
  115. package/src/runtime/styles.ts +54 -12
  116. package/src/runtime/tasks.ts +63 -12
  117. package/src/task-events.ts +232 -0
  118. package/src/team-samples.ts +74 -0
  119. package/src/team.ts +342 -0
  120. package/src/webclient.ts +45 -4
  121. package/src/webrequests.ts +5 -0
  122. package/src/websources.ts +30 -12
  123. package/src/workflow.ts +135 -18
  124. package/src/workspace-export.ts +16 -1
@@ -33,12 +33,17 @@ src/
33
33
  rows and columns from the response schema, write-back from collection and item paths, notes), catalog
34
34
  files, load/insert/replace, sourceFromService
35
35
  workspace-export.ts (sprint 67) a workspace's components as a file (pgkiln-workspace/1) and importWorkspace (one transaction)
36
+ team.ts (sprint 113) Team Development's data: workspaceDevelopers (members and administrators: assignees, @mentions),
37
+ issueHtml (markdownHtml + mentions), recordMentions, logIssue (history), teamSetup, teamCounts, pageIssues,
38
+ exportTeam / importTeam (the workspace export's "team" part)
39
+ team-samples.ts (sprint 113) the set-up wizard's samples per builder language (English; add a key for another)
36
40
  subscriptions.ts application types and subscriptions (migration 056): offers, subscribe, refresh, publish, in sync
37
41
  workingcopy.ts working copies (migration 055): create, three-way compare per component (base, main, copy),
38
42
  merge into the main application or refresh the copy, both through cli/replace.ts
39
43
  cli/ the command line: main.ts (commands, help, exit codes), apps.ts (connect, export,
40
44
  read, import), files.ts (directories, zip), diff.ts, replace.ts (import --replace in place),
41
- mcp.ts (`pgkiln mcp`: the MCP server for AI coding agents, chapter 20)
45
+ mcp.ts (`pgkiln mcp`: the MCP server for AI coding agents, chapter 20), only.ts (sprint 116:
46
+ `import --replace --only pages/12`, the named files merged over the application's current export)
42
47
  app.ts / server.ts Fastify setup / entry point
43
48
  db.ts the owner and shared runtime pools, `runtime` (the current scope's: runtimeScope), appTx() (SET LOCAL ROLE + pgkiln.* settings, NOTICEs to the debug log), savepoints
44
49
  workspace-db.ts isolated workspaces (090): the isolated applications (cached 5 s), a pool per workspace login (passwords from
@@ -55,7 +60,10 @@ src/
55
60
  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
56
61
  remember.ts "Keep me signed in": rotating persistent sign-in tokens
57
62
  workflow.ts workflows: step checks, the runner with parallel branches (NOTIFY + polling), invoke_api steps
58
- (the call between two transactions, with a lease), Advisor references, the diagram
63
+ (the call between two transactions, with a lease), Advisor references, the diagram;
64
+ (sprint 114) send_mail and draft steps, switch cases on task outcomes, the diagram as a standalone SVG
65
+ task-events.ts (sprint 114) task events (complete, expire, fail: SQL, mail, start a workflow) and built-in task
66
+ notifications from e-mail templates: checks, the actions as the app role, the meta.task_hook outbox runner
59
67
  process-jobs.ts background execution chains: the job queue (SKIP LOCKED, NOTIFY + polling), running a job as the app role
60
68
  api.ts REST API tokens for PostgREST, API role checks
61
69
  accounts.ts account settings and the password policy
@@ -88,6 +96,9 @@ src/
88
96
  objects, type reporting, roles viewer/editor/administrator as schemes EDITOR and ADMIN, page 1 a Data
89
97
  Reporter), reportingApps(), reportingAppCount() (meta.reporting_app_count, for the workspace home)
90
98
  tabledef.ts (sprint 95) a table as a definition: readTable(), checkTable(), tableSql() (CREATE, or ALTER from the catalog's version)
99
+ datasec.ts (sprint 119, WS-13) data security per table: readSecurity() (policies, column privileges per role, the
100
+ masking view and its configuration in the view comment), checkSecurity(), securitySql() (GRANT / REVOKE,
101
+ the masking view owned by <schema>_masking); the page is builder/data-security.ts
91
102
  sqlformat.ts (sprint 93) formatSql(): the worksheet's Format (clauses per line, keyword case; strings and comments kept)
92
103
  sqlplan.ts (sprint 92) EXPLAIN (FORMAT JSON) as a tree: parsePlan() (self time, slowest step, misestimates), planText()
93
104
  quicksql.ts Quick SQL: shorthand parser and PostgreSQL DDL generator (unit tested)
@@ -103,7 +114,12 @@ src/
103
114
  geocode.ts the installation's geocoder for address items (GEOCODER_URL, Nominatim search API)
104
115
  mvt.ts Mapbox Vector Tile encoding for map layers served as tiles
105
116
  yamltext.ts the text style of the directory export: a strict YAML subset, written and read
106
- webclient.ts outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits
117
+ webclient.ts outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits;
118
+ (sprint 118) a request's scope (OutboundScope): the workspace's network access list, checked on every hop
119
+ (checkUrl/scopeProblem), refusals reported to the scope
120
+ network-acl.ts (sprint 118, WS-9) workspace network access lists (meta.workspace.network_*): scopeForApp/scopeForWorkspace
121
+ (no cache), parseHostList, recordRefusal/purgeRefusals (meta.network_refusal, 7 days), mailHostAddress
122
+ (a workspace mail service's SMTP host: both lists, resolved once, the checked address connected to)
107
123
  datapump.ts (sprint 103, DA-16) Schema Export / Import jobs (meta.dump_job): findTools (pg_dump/pg_restore ≥ the
108
124
  server's major), startExport (pg_dump, argument array, PGPASSWORD), readToc/parseToc (pg_restore --list),
109
125
  startImport (pg_restore -f - run in one transaction between schema renames; data-only in FK order),
@@ -130,7 +146,10 @@ src/
130
146
  or XOAUTH2, Microsoft Graph sendMail, Amazon SES v2 raw MIME with signV4, Resend, Postmark, SendGrid,
131
147
  Mailgun, log; MailError says whether a retry may help; client-credentials token cache; settingsProblems),
132
148
  mail.ts (sendWith(): service enabled, allowed sender, secret decrypted; mailTick(): claim with SKIP LOCKED,
133
- send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener)
149
+ send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener);
150
+ (sprint 118) the service of meta.mail_service_for_app (the app's, else its workspace's own), each attempt's
151
+ provider and duration, serviceSettings()/verifyService(): a workspace service's checks (no base or token URL,
152
+ its SMTP host through network-acl.ts mailHostAddress)
134
153
  ai/ AI services (migration 060): types.ts (the provider interface, AiError kinds),
135
154
  anthropic.ts (Claude through @anthropic-ai/sdk: streamed, effort, structured outputs via
136
155
  output_config.format, refusal fallbacks, stop_reason checks, typed SDK errors), openai.ts (the openai
@@ -138,7 +157,10 @@ src/
138
157
  limits, the call, meta.ai_usage), requests.ts (meta.ai_generate from SQL: runPendingAi() after an sql
139
158
  process, aiRequestTick() in the scheduler, 24-hour purge), chat.ts (conversations with tools, migration
140
159
  061: chat() runs the tool loop on a provider-format history (Claude: streamed, strict tools, tool_choice
141
- auto, content appended unchanged; OpenAI: strict function tools), limits and usage per provider call)
160
+ auto, content appended unchanged; OpenAI: strict function tools), limits and usage per provider call;
161
+ (121) an agent's effort (Claude output_config.effort, OpenAI reasoning_effort) and output limit).
162
+ Providers (121): anthropic, openai, gemini (OpenAI-compatible endpoint, GEMINI_BASE_URL), openai_compatible
163
+ (Ollama, vLLM, Azure OpenAI; base URL required, key optional): service.ts serviceKey(), baseUrlFor(), providerLabel()
142
164
  debug.ts debug messages: DebugLog (levels, timed steps, NOTICEs of meta.debug from appTx), started in
143
165
  loadContext, stored after the response (onResponse hook → meta.debug_save), hourly purge
144
166
  icons.ts icon helper (sprite in public/icons.svg)
@@ -154,9 +176,10 @@ src/
154
176
  shortcuts.ts (103) "NAME" shortcuts in static content, help texts and confirm messages
155
177
  render.ts page chrome (nav, breadcrumb), dynamic action JSON, theme (the page's nonce'd <style>, light/dark and style switches)
156
178
  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
157
- style (user choice, default), themeCss() (only hex values and constants reach the CSS)
179
+ style (user choice, default), themeCss() (only hex values and constants reach the CSS); (sprint 117) NAV_APPEARANCES
180
+ (Pillar Light / Dark), navAppearance() → the <body> classes nav-pillar-*, the header strip (--strip)
158
181
  template-options.ts template options: the fixed CSS class list per region and button, templateClasses() (unknown values ignored)
159
- regions.ts region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges)
182
+ 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)
160
183
  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
161
184
  (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;
162
185
  items.ts: lovOptions, searchLov/lovLookup for popup LOVs, served by POST /a/:alias/:page/lov/:item/search in routes.ts)
@@ -193,7 +216,8 @@ src/
193
216
  template-components.ts template components: template language (allow-list, directives, escaping), plug-in files, report column templates
194
217
  builtin-components.ts built-in template components (ut_avatar, ut_badge, ut_comments, ut_media_list, ut_metric_card, ut_timeline)
195
218
  template-region.ts template_component region
196
- tasks.ts task list region and task actions (approvals); (094) the vacation rule panel and route
219
+ tasks.ts task list region and task actions (approvals); (094) the vacation rule panel and route;
220
+ (sprint 114) custom outcome buttons, the Fail event and recovery of a failing completion SQL
197
221
  data-reporter.ts Data Reporter region (migration 057): sources from the region's config, checkDef (offered columns, whitelists),
198
222
  reportQuery/chartQuery, the list and editor (GET form), save/delete routes (meta.save_data_report);
199
223
  (sprint 110) dataset sources (resolveSources), edit_authz / admin_authz / publishing, pins (a preference),
@@ -205,8 +229,20 @@ src/
205
229
  schemas from items, answers into items), aiInputs/aiOutputs for its dynamic action (route in routes.ts)
206
230
  assistant.ts AI assistant region (migration 061): config checks, tool schemas and argument checks, context queries
207
231
  and SQL tools as the app role (rolled back unless "writes"), REST tools, meta.ai_conversation per
208
- session, formatAnswer (escaped), send/clear routes
209
- ai-filter.ts natural-language filters on a report ("ai_filter"): columns → structured output → checked → r<id>_f/q/s/d
232
+ session, formatAnswer (escaped), send/clear routes; (121) "agent": an AI agent's service, prompt, tools,
233
+ steps and authorization; links of navigate tools under the answer, browser actions once (__AIACT<id>)
234
+ ai-agents.ts (121) AI agents and AI tools (meta.app.ai_agents / ai_tools): checks (agentProblems, aiToolProblems,
235
+ definitionProblems), agentFor(), prepareTools() (authorization schemes, navigate pages the user may
236
+ open, strict schemas), runAgentTool() (sql: read-only transaction as the app role with a time limit;
237
+ function: named arguments, committed; rest; javascript: queued for the browser; navigate: URL and
238
+ checksum built here), logToolCall() (meta.ai_tool_call, debug level 4, 30-day purge)
239
+ ai-filter.ts "Ask in your own words" on a report ("ai_filter", sprint 112: AI interactive reports): the box, the chips
240
+ form (Edit/Remove/Undo, undo history in the session), ask and chips routes; an AI service's structured
241
+ output (planSchema) or the phrase parser, then ir-plan.ts
242
+ ir-plan.ts what a question may set: checkPlan (shown columns, whitelists, computeSql), applyPlan (→ the report's
243
+ URL parameters), chipsOf/editChip/removeChip (a chip = one URL parameter value, edits checked again)
244
+ ir-phrases.ts the rule-based parser without an AI service: phrase tables per language (en, nl, de), clauses →
245
+ a RawPlan; values looked up among the report's rows through a Lookup (query parameter)
210
246
  pdf.ts report PDFs with report layouts (pdfkit); rows from a cursor in batches (tablePdf takes batches)
211
247
  search.ts search region and search configurations (migration 080): words as ILIKE parameters, table/sql/list
212
248
  sources as the app role in savepoints, marked results, configColumns/searchConfigProblems for the Advisor
@@ -230,7 +266,10 @@ src/
230
266
  wizards.ts create page wizards: step 2 forms per page type (defaults from meta.wizard_defaults), POST → meta.generate_page
231
267
  (the generators are PL/pgSQL in migration 047: catalog, defaults, form/cards/calendar/chart/map/facets/master-detail)
232
268
  home.ts App Builder home at /builder/apps and /builder (tiles, applications report/cards, Recent; /builder redirects
233
- to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities
269
+ to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities;
270
+ (116) Updated by, working copies and the application lock in the report and the cards
271
+ app-updates.ts (sprint 116, migration 125) who changed an application last: developer() notes a builder POST under
272
+ /apps/:id or /pages/:pid (or a Create / Import), an onSend hook records a success in meta.app_change
234
273
  workspace-home.ts (sprint 109, migration 119) the Workspace home /builder/home, opened after sign-in: tool cards (Data Reporter
235
274
  when GET /builder/reporter exists), workspace message edited in place (workspaceAdmin), Summary, Top
236
275
  applications / users / developers over meta.developer.home_timeframe, System message (src/release-check.ts),
@@ -256,9 +295,22 @@ src/
256
295
  availability.ts Application → Availability (migration 083): status, message, users, build status (Run only is
257
296
  enforced by locks.ts blockingLock); availabilityBadge() in the application header
258
297
  feedback.ts Application → Feedback (migration 084): the setting, the list with filters, status and answers
298
+ team.ts (sprint 113, migration 122) Builder → Team Development /builder/team: issues (list with filters and saved views,
299
+ board by label group or milestone with a Move form per card, issue page with Markdown, comments, canned
300
+ responses, @mentions, history), labels and groups, milestones, templates, the set-up wizard; Make an issue
301
+ from feedback and developer comments; pageIssuesNote (Page Designer), appIssues (App Home), teamHomeBlock
302
+ (Workspace home). Every id from a request is looked up in the current workspace
259
303
  region-help.ts the Attributes (JSON) help per region type, with links to the guide
260
304
  mail.ts Workspace utilities → Mail services (administrators: providers, write-only secret, allowed senders,
261
- applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel)
305
+ applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel);
306
+ serviceForm/formValues/runCheck shared with workspace-mail.ts (sprint 118)
307
+ mail-queue.ts (sprint 118, WS-9) Administration → Mail queue (/builder/mail-queue): queueScope (administrators: all or
308
+ ?ws=; workspace administrators: the current workspace), figures, per hour, per workspace / application,
309
+ slowest provider calls, failures; Retry / Purge one or all failed, scope checked again per mail
310
+ network-access.ts (sprint 118, WS-9) Administration → Network access (/builder/network): the installation's list, a workspace's
311
+ list (workspaceAdmin), Check a URL (nothing called), the workspaces (administrators), refused calls
312
+ workspace-mail.ts (sprint 118, WS-9) a workspace's own mail service (/builder/workspaces/:id/mail, WORKSPACE_<id>): its
313
+ administrators only, write-only secret, checks through mail.ts runCheck with the workspace's guard
262
314
  shared.ts Shared Components and access control
263
315
  designer.ts page designer: component tree (with computations and branches), layout canvas and gallery, property editor, toolbar;
264
316
  (sprint 86) GET /builder/apps/:app/pages/:no, /builder/pages/:id redirects browsers there (designerUrl in ui.ts)
@@ -276,6 +328,7 @@ src/
276
328
  object-browser.ts (sprint 75) the Object Browser: objects by type, system objects hidden, a table in tabs, column actions as SQL to review
277
329
  table-editor.ts (sprint 95) Table Properties: GET/POST /sql/objects/table (create, edit ?o=, ?template=), fromForm(), Preview / Apply
278
330
  (one transaction) / Open in the worksheet
331
+ data-security.ts (sprint 119) a table's Security: GET/POST /sql/objects/security?o= (policies, roles × columns, masks), Preview / Apply
279
332
  object-actions.ts (sprint 94) an object's ⋯ menu (objectMenu) in the worksheet and the Object Browser: Quick DDL (objectDdl), Drop with
280
333
  dependents, Add index / trigger / policy as drafts; GET /sql/objects/action, /sql/objects/panel (Open in a panel)
281
334
  data-modeler.ts (sprint 98) SQL Workshop → Data Modeler: /sql/modeler (diagrams, meta.sql_diagram, 111), /:id (SVG), /:id/objects, /layout,
@@ -320,7 +373,8 @@ src/
320
373
  ldap.ts Users → LDAP directories
321
374
  documents.ts document template preview (Shared Components)
322
375
  pwa.ts Settings → Progressive Web App (icon upload)
323
- themeroller.ts Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose
376
+ themeroller.ts Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose;
377
+ (sprint 117) navigation appearance and header strip colours (application and per style), the preview's menu
324
378
  subscriptions.ts Shared Components → Subscriptions: subscribe, refresh, unsubscribe, subscribers and publish; the note under a component
325
379
  reporter.ts page designer: Data Reporter settings (sources: table or view, offered columns, labels, masks; sharing;
326
380
  (sprint 110) a dataset as a source, who may edit, who may moderate, publishing)
@@ -337,6 +391,8 @@ src/
337
391
  workspace's applications, the module › template › handler tree, handler forms, Try it (inject with a
338
392
  short-lived token), Run only / lock checks
339
393
  workflows.ts workflow versions, diagram and instances (Shared Components)
394
+ workflow-migrate.ts (sprint 114) migrating running workflow instances to a newer version (map, preview, apply with
395
+ meta.migrate_workflows) and the diagram as an SVG file (PNG in builder.js)
340
396
  process-jobs.ts page designer: the Jobs tab of a background chain process
341
397
  template-spec.ts template component property form (Shared Components)
342
398
  websources.ts web credentials and REST data sources: property specs, secret status, Test, suggested columns,
@@ -359,13 +415,18 @@ src/
359
415
  ai-builder.ts App Builder AI (migration 062): the builder's AI service (meta.builder_ai), SQL Workshop → AI (SQL from a
360
416
  question, shown not run; explain), describe tables (meta.ai_table_note, COMMENT ON, AI drafts),
361
417
  create pages with AI (proposals checked by checkProposals, created with meta.generate_page)
362
- assistant.ts page designer: AI assistant settings and a report's "Ask in your own words" (AI service, placeholder)
418
+ 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)
363
419
  ai.ts Workspace utilities → AI services (administrators: services, write-only encrypted keys, access and
364
420
  daily limits per app, Test, usage log) and Activity → AI usage per application
421
+ ai-agents.ts (121) Shared Components → AI Agents: the agent and tool forms (checked before saving, renames follow
422
+ into agents and regions), toolCallTable() (Activity → AI usage → Tool calls), agentOptions()
365
423
  supporting.ts supporting objects: review page, running the install/upgrade/deinstall scripts as the app's role in one transaction
366
424
  public/
367
- app.css theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*)
368
- 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)
425
+ app.css theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*;
426
+ (sprint 117) navigation tree states, RTL via logical properties, body.nav-pillar-*, u-color-*-subtle, the busy bar)
427
+ app.js client runtime: dialogs (dialog_closed actions), popup LOVs (sprint 115: the next page loads on scroll through an
428
+ IntersectionObserver, ‹/More without one), dynamic actions (focus, classes, messages; sprint 115: wait_popup /
429
+ 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)
369
430
  code-editor.js, .css builder code editor: enhances <textarea data-code>, highlighting, suggestions (no dependencies);
370
431
  (sprint 108) the current line, and read-only <pre data-code-view="sql|plpgsql|json|html"> highlighted;
371
432
  its colours are the --ce-* tokens in builder.css
@@ -421,11 +482,15 @@ test/
421
482
  page-logic.test.ts download, chain (background jobs) and workflow processes, function/app branches, dialog_closed (HR page 28)
422
483
  code-editor.test.ts code editor: completions scoped to the app's role, the check, marked fields
423
484
  builder-home.test.ts App Builder home: search, sort, views, Recent, Create/Import pages, dashboard, utilities
485
+ app-list.test.ts (116) the App Builder list's Updated by, working copies and lock; what counts as a change
486
+ import-only.test.ts (116) pgkiln import --replace --only: a page or component file, refusals
424
487
  charts.test.ts chart markup per kind (geometry as classes), gauges, Gantt time axis and dependencies, pyramid, polar, range, box plot, stock, drill-down links
425
488
  calendar.test.ts calendar views, create links, moving events (pure and over HTTP)
426
489
  rest-sources.test.ts REST data sources, web credentials, SSRF checks, invoke_api (mock service + HR page 23)
427
490
  rest-modules.test.ts (sprint 104) modules, templates, PL/pgSQL and media handlers, OpenAPI, the builder's tree and Try it
428
491
  workflow-invoke.test.ts workflow invoke_api steps: the call between transactions, faults, retry, lease, Advisor, export (mock service)
492
+ workflow-outcomes.test.ts (sprint 114) custom task outcomes, task events and notifications, fail recovery, send_mail and draft
493
+ steps, migrating running instances, the SVG export (HR part 67: SALARY_CHANGE)
429
494
  large-tables.test.ts row ranges, max_rows, row limits, lazy regions, region caching, streamed downloads (HR page 25)
430
495
  grid.test.ts interactive grid: aggregates, layouts per user, saved grid reports, master-detail, row actions (HR page 27)
431
496
  custom-auth.test.ts custom authentication: function body, named function, post-authentication code, builder settings
@@ -437,7 +502,11 @@ test/
437
502
  builder-parity.test.ts lists (HR page 31), page and application locks, comments, developers, supporting objects
438
503
  page-wizards.test.ts create page wizards: catalog defaults, every page type generated and rendered, refusals, the builder steps
439
504
  theme-styles.test.ts Theme Roller style variants (checks, CSS, user choice per app, builder page), template options, base style Iris
505
+ theme-pillar.test.ts (sprint 117) Pillar Light / Dark appearances and the header strip: checks, CSS, runtime classes, Theme Roller, export
440
506
  workspaces.test.ts workspaces (064): Default, administrators' pages, current workspace, refused apps, imports and copies
507
+ mail-network.test.ts (sprint 118) network access lists (page process refused and logged in debug, narrowing only, redirects,
508
+ the page), a workspace's mail service (sending, SMTP host on the list), the Mail queue (yesterday's
509
+ SMTP failure, Retry, Purge, counts, scope)
441
510
  gallery.test.ts the App Gallery: every starter created from its review with all its pages rendering; sample apps (admins)
442
511
  builder-apex-screens.test.ts sprint 61: sign-in with a workspace, message and banner, utilization, SQL Workshop home, groups, reports
443
512
  workspace-isolation.test.ts isolated workspaces (090): logins, RLS on meta, app_id, roles, SQL Workshop, scripts, imports
@@ -457,6 +526,8 @@ test/
457
526
  ai-mock.ts a local mock of the Claude Messages API (SSE stream) and OpenAI Chat Completions
458
527
  helpers.ts a cookie-keeping test browser
459
528
  e2e/responsive.test.ts browser tests at phone/tablet/desktop widths (Playwright)
529
+ e2e/admin-mail-network.test.ts (sprint 118) Mail queue, Network access and a workspace's mail service at 390 px without JavaScript
530
+ e2e/pillar.test.ts (sprint 117) Pillar appearances: axe in light and dark, subtle colours, current vs parent entry, Arabic RTL, 390 px, preview
460
531
  e2e/code-editor.test.ts the code editor in a browser: highlighting, keys, suggestions, touch, screen readers, syntax colours at AA in both themes (sprint 108)
461
532
  e2e/data-modeler.test.ts (sprint 98) the Data Modeler in a browser: drag, save, reload, undo/redo, zoom, mini-map, exports, phone
462
533
  e2e/worksheet.test.ts (sprint 91) the SQL Worksheet in a browser: run keys, tabs, navigator, drag and drop, splitters, phone, no JavaScript;
@@ -245,6 +245,8 @@ application. The base style and colours under Settings → Theme are the *Standa
245
245
  |---|---|
246
246
  | Accent colour, header colour | `#rrggbb` (or "as the base"), for the light theme |
247
247
  | Accent and header colour in dark mode | `#rrggbb` (or the base style's dark palette), for the dark theme; choose light colours (text on the accent is dark there) |
248
+ | Navigation appearance | *As the application*, *Default* (the base style's header and menu), *Pillar Light* or *Pillar Dark*, see [below](#navigation-appearances-pillar-light-and-pillar-dark) |
249
+ | Header strip colour, also for dark mode | `#rrggbb` or an item reference (else the application's strip, else the accent) |
248
250
  | Font | *System* (default), *Humanist sans*, *Geometric sans*, *Serif*, *Rounded*, *Monospace* (font stacks of fonts on the device; nothing is downloaded) |
249
251
  | Font size | 14, 15 (default), 16 or 17 px |
250
252
  | Corners | Square, 4, 8 (default) or 14 px, for regions, buttons and fields |
@@ -276,10 +278,56 @@ per tenant, environment or user group:
276
278
  a style themselves get the first style (in the list's order) whose condition holds, else the
277
279
  default style. The condition runs as the application's database role in the page's transaction;
278
280
  an error counts as *false* and is written to the [debug messages](06-processing.md#debug-messages).
279
- - **Dynamic colours.** Instead of a picked colour, any of a style's four colours may be an item
281
+ - **Dynamic colours.** Instead of a picked colour, any of a style's colours may be an item
280
282
  reference such as `&APP_BRAND_COLOUR.`: the item's value in session state (set by a computation,
281
283
  an application process after login, a form…), used when it is a `#rrggbb` colour and ignored
282
284
  otherwise, so a stored value can never become anything but a colour in the CSS.
283
285
 
284
286
  Together: one style *Tenant brand* with condition `:APP_BRAND_COLOUR is not null` and accent
285
287
  `&APP_BRAND_COLOUR.` gives each tenant its colour from a table, read once after sign-in.
288
+
289
+ ## Navigation appearances: Pillar Light and Pillar Dark
290
+
291
+ APEX 26.2's Universal Theme adds *Pillar* appearances for the header and the navigation menu. In pgkiln:
292
+ **Theme Roller → Navigation appearance** (for the whole application) or a style's own *Navigation appearance*:
293
+
294
+ | Appearance | Look |
295
+ |---|---|
296
+ | **Default** | The base style's header and menu (Iris: a dark header and menu; Standard: a navy header and a white menu) |
297
+ | **Pillar Light** | Header and menu on the page's own light surfaces (in dark mode its dark ones), a line under the header |
298
+ | **Pillar Dark** | Header and menu as one dark column in the header colour; in dark mode a darker one |
299
+
300
+ Both have a **header pillar strip** across the top of the header, in the *Header strip colour* (light and dark mode,
301
+ on the Theme Roller page or per style; a style may take it from an item, like its other colours), else the accent,
302
+ and show the **current page as a filled pill** in the accent. Pillar Light replaces the header colour with the page's
303
+ surface, so the strip carries the brand colour. A style's appearance wins over the application's; *Default* in a style
304
+ switches a pillar appearance off. The appearance works with a side and a top menu, and on tablets and phones in the
305
+ drawer. It is stored as `"appearance"`, `"strip"` and `"strip_dark"` in `meta.app.theme` (and in each style), so it
306
+ travels with export and import; only the two keys of the list and `#rrggbb` colours reach the page (classes
307
+ `nav-pillar nav-pillar-light` / `nav-pillar-dark` on `<body>`, `--strip` in the nonce'd `<style>`).
308
+
309
+ ### The navigation tree
310
+
311
+ In every appearance (sprint 117) the menu tells three states apart: the **current page** is filled, in the accent,
312
+ with a bar at the start of the entry (a pill in the pillar appearances); its **parent entries** (the trail) are bold
313
+ with an accent icon but not filled, and the open parent's sub-menu hangs on an accent guide line; the **selected**
314
+ entry (keyboard focus) has a ring inside the menu. A page that is not in the menu marks its nearest menu ancestor as
315
+ the trail.
316
+
317
+ ### Right to left
318
+
319
+ Arabic, Hebrew, Persian and Urdu pages (`dir="rtl"`) mirror the chrome: the menu sits on the right, the drawer
320
+ slides in from the right on tablets and phones, the current page's bar, the guide lines and the menu's chevrons turn
321
+ around, menus open from the other side and reflowed report cards are aligned to the start.
322
+
323
+ ### Subtle colour utilities and the processing indicator
324
+
325
+ The classes `u-color-1-subtle` … `u-color-15-subtle` and `u-color-success-subtle`, `u-color-danger-subtle`,
326
+ `u-color-warning-subtle`, `u-color-info-subtle`, `u-color-neutral-subtle` give an element a tinted background with
327
+ readable text (WCAG AA in light and dark mode, in every base style), for static content, HTML expressions and
328
+ template components, e.g. `<span class="u-color-4-subtle">Approved</span>`.
329
+
330
+ A region that is busy (a dynamic action, a refresh) is dimmed slightly after 150 ms, so quick answers don't flicker,
331
+ and shows a thin moving bar along its top (a still bar when the device asks for reduced motion); the wait popup's
332
+ spinner is lighter too.
333
+
@@ -35,7 +35,7 @@ any (see [what is not exported](03-builder.md#export-format)).
35
35
  | `pgkiln migrate [--example <name>]` | Applies the migrations that were not applied yet, then optionally `examples/<name>/` (same as `npm run db:migrate` / `npm run example:hr`; `--root` and `--seed` as in `scripts/migrate.ts`) |
36
36
  | `pgkiln apps [--json]` | Lists the applications: alias, number of pages, name |
37
37
  | `pgkiln export <alias> [--format json\|dir\|text] [--out <path>]` | `json` (default): the `pgkiln/2` document with sorted keys, to `--out` or standard output. `dir`: a directory (default `./<alias>`), see below. `text`: the same directory in YAML with the code inline ([text files](#text-files-apexlang)) |
38
- | `pgkiln import <path> [--alias <alias>] [--replace] [--check [--force] \| --dry-run]` | Imports a JSON export, an application directory or a `.zip` of one. `--alias` gives the copy another alias. `--replace` updates the application with that alias in place (after a [backup](03-builder.md#backups)). `--check` checks the application before it commits, `--dry-run` only checks ([below](#checking-before-an-import)) |
38
+ | `pgkiln import <path> [--alias <alias>] [--replace [--only <file>]…] [--check [--force] \| --dry-run]` | Imports a JSON export, an application directory or a `.zip` of one. `--alias` gives the copy another alias. `--replace` updates the application with that alias in place (after a [backup](03-builder.md#backups)); with `--only pages/12` (repeatable) only that page or component file ([below](#importing-one-page-or-component)). `--check` checks the application before it commits, `--dry-run` only checks ([below](#checking-before-an-import)) |
39
39
  | `pgkiln diff <alias> <path> [--name-only \| --quiet]` | What differs between the application in the database and a directory (or JSON file, or zip) |
40
40
  | `pgkiln ddl <schema> [--no-comments] [--no-grants] [--out <file>]` | The DDL of a schema's objects, in an order that runs (as SQL Workshop → DDL, [chapter 3](03-builder.md#sql-workshop)) |
41
41
  | `pgkiln compare <source> <target> [--script]` | Compares two schemas: `+` only in the source, `-` only in the target, `~` different; exit code 1 when they differ. `--script` writes the script that makes the target like the source (drops commented out); nothing is run |
@@ -210,6 +210,26 @@ pgkiln diff hr apps/hr # on the target: what would cha
210
210
  pgkiln import apps/hr --replace # deploy
211
211
  ```
212
212
 
213
+ ### Importing one page or component
214
+
215
+ (sprint 116; APEX 26.2: APEXlang file-level import) With `--replace`, `--only` imports just the named files of a
216
+ directory export (or a .zip of one) and leaves the rest of the application as it is in the database:
217
+
218
+ ```sh
219
+ pgkiln import apps/hr --replace --only pages/12 # page 12 with its regions, items, buttons …
220
+ pgkiln import apps/hr --replace --only shared/lovs/jobs.yaml # one shared component
221
+ pgkiln import apps/hr --replace --only pages/12 --only shared/lovs # several: repeat --only
222
+ ```
223
+
224
+ `pages/12` (or just `12`) is page 12's folder whatever its name, so a renamed page still matches; any other value is
225
+ a file or folder path inside the export. A page or file that the directory no longer has is removed from the
226
+ application. How it works: pgkiln exports the application in the directory's style, takes the named files from the
227
+ directory, and imports the result with `--replace` as usual: one transaction, a backup first, `--check` and
228
+ `--dry-run` work the same, and what belongs to the installation is kept. It says how many of the named files differ
229
+ (on standard error). `--only` refuses without `--replace`, for a JSON file, for a path outside the export and for a
230
+ selection that matches nothing in the directory or the application (exit code 2). A component that another file
231
+ refers to by name (a list of values used on a page, say) has to exist after the import, as with any import.
232
+
213
233
  ### Checking before an import
214
234
 
215
235
  An import doesn't need the application's tables, columns and functions to exist (neither does APEX's):
@@ -53,6 +53,16 @@ The checks on every outgoing request (`src/webclient.ts`), against server-side r
53
53
  Keep the allow-list as short as you can. `*` lets developers call any public host from the
54
54
  server; it never opens private addresses.
55
55
 
56
+ **A workspace's network access list** (sprint 118; APEX 26.2 workspace network ACLs) narrows this
57
+ list for one workspace: under Administration → [Network access](03-builder.md#network-access), its
58
+ administrators can limit its applications to some hosts (same entry syntax, without `*`). A call made
59
+ for an application of that workspace must then match the workspace's list *and* the installation's,
60
+ on every redirect hop; the address checks above stay with `PGKILN_REST_PRIVATE_HOSTS` alone, so a
61
+ workspace can never widen what the installation allows. It applies to every path above: REST data
62
+ sources (including write-back, synchronisation and the response cache), `meta.web_request`, invoke
63
+ API, token endpoints, object storage and REST source catalogs. Refusals are logged in the
64
+ application's debug log and listed under *Refused calls*.
65
+
56
66
  **Changing `PGKILN_SECRET_KEY`** makes the stored secrets unreadable: pgkiln then reports that
57
67
  the secret must be entered again. Keep the key with your other server secrets, outside the
58
68
  database: a database dump alone does not reveal the secrets.
@@ -323,6 +333,8 @@ values, processes and workflow steps refer to sources and credentials by name, s
323
333
 
324
334
  - Outgoing calls are off until the administrator sets `PGKILN_REST_ALLOWED_HOSTS`; private and
325
335
  internal addresses need `PGKILN_REST_PRIVATE_HOSTS` as well.
336
+ - A workspace's [network access list](03-builder.md#network-access) narrows the allow-list for its
337
+ applications (it can't widen it).
326
338
  - Secrets are encrypted with a key outside the database, write-only in the builder, excluded from
327
339
  exports and from the runtime role, and never logged. Use **Valid for URLs** so a credential is
328
340
  only ever sent to its own service.
@@ -7,8 +7,10 @@ it exports the application as files, edits them with its own file tools, shows t
7
7
  and imports them again. Laravel developers know the idea from Laravel Boost.
8
8
 
9
9
  This is separate from the AI features *inside* applications and the builder (AI assistant regions,
10
- *Generate with AI*): those call a model from pgkiln; here an agent on the developer's machine calls
11
- pgkiln.
10
+ [AI agents with tools](03-builder.md#ai-agents) in Shared Components, *Generate with AI*): those call a
11
+ model from pgkiln; here an agent on the developer's machine calls pgkiln. An application's AI agents
12
+ and tools are part of its files (`app.json`: `ai_agents`, `ai_tools`), so a coding agent can read and
13
+ change them like any other component.
12
14
 
13
15
  ## Setting it up
14
16
 
@@ -50,7 +52,7 @@ directory the agent started the server in (the project).
50
52
  | `describe_schema` | schemas with tables, views and functions; or one table with columns, constraints, indexes, RLS policies and triggers | no |
51
53
  | `generate_ddl` | the DDL of a schema's objects, in an order that runs: a start for a migration script | no |
52
54
  | `compare_schemas` | the differences between two schemas and a script that makes the target like the source (not run) | no |
53
- | `run_query` | one SQL statement, read-only, rows as JSON | no |
55
+ | `run_query` | one SQL statement, read-only, rows as JSON; with `alias` (and `user`) as that application's role and user | no |
54
56
  | `search_docs` | searches this user guide, the parity matrix and SECURITY.md | no |
55
57
  | `recent_errors` | the latest errors and refused requests from the activity log | no |
56
58
  | `export_app` | writes an application to a directory (default `apps/<alias>`, format `text`) | files on disk |
@@ -83,7 +85,13 @@ migration scripts, not in the application files (`run_query` can't change them a
83
85
  columns whose names contain *password*, *secret*, *token*, *hash* or *api_key* are shown as
84
86
  `(hidden)`. That keeps credentials out of the agent's context by accident; it is not an access
85
87
  control: the server runs as the owner role, like the command line, and is meant for a
86
- developer's own machine. Don't point it at production; deploy with `pgkiln import --replace`
88
+ developer's own machine.
89
+ - **As an application's user.** (sprint 119) `run_query` with `alias` runs the statement as that application's
90
+ database role, with `meta.app_id()`, `meta.app_user()` (`user`, default `nobody`) and `meta.has_role()` (the
91
+ user's roles in the application) set, so grants, column privileges, row level security and masking views apply as
92
+ on that user's pages ([chapter 8](08-security.md#data-security-per-table-rows-columns-and-values)). Use it to check
93
+ what a user sees, or let an agent look at data the way the application does. It is no sandbox either: the
94
+ connection is still the owner's. Don't point it at production; deploy with `pgkiln import --replace`
87
95
  from git instead.
88
96
  - **Writes** are only `export_app` (files; it refuses a non-empty directory that isn't an export,
89
97
  so it can't overwrite your project) and `import_app` (the database, in one transaction). Both are
@@ -40,6 +40,8 @@ Then open http://127.0.0.1:3100/a/hr and sign in as `king`, `blake`, `jones`, `a
40
40
  | `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) |
41
41
  | `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 |
42
42
  | `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) |
43
+ | `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) |
44
+ | `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`) |
43
45
 
44
46
  The files run in order, each once (recorded in `public.pgkiln_seed`), so new ones can be added
45
47
  later. pgkiln's own tests use this application as their fixture (`npm test` installs it first).
@@ -0,0 +1,97 @@
1
+ -- =====================================================================
2
+ -- HR example, part 64: an AI agent with tools (sprint 111;
3
+ -- docs/guide/03-builder.md, "AI agents"; APEX 26.1: AI Agents)
4
+ --
5
+ -- Shared Components → AI Agents:
6
+ -- - Tools:
7
+ -- top_earners (sql) employees by salary, highest first,
8
+ -- optionally of one department: a query
9
+ -- run as hr_app (row level security
10
+ -- applies) in a read-only transaction
11
+ -- open_employee (navigate) a link to the employee form (page 3)
12
+ -- with P3_EMPNO: pgkiln offers it only
13
+ -- to users who may open page 3
14
+ -- (MANAGER) and builds the checksum
15
+ -- give_raise (function) hr.give_raise(p_empno, p_pct): changes
16
+ -- data, only offered to managers
17
+ -- note (javascript) shows a message in the browser after
18
+ -- the answer (the custom event
19
+ -- "hr_agent_note" on page 46)
20
+ -- - Agent HR_AGENT: the AI service HR_ASSISTANT, a system prompt, low
21
+ -- reasoning effort, the four tools, at most 4 steps per question.
22
+ --
23
+ -- Page 46 "HR agent": an AI assistant region that names the agent. Ask
24
+ -- e.g. "Who in Sales earns most?": the agent calls top_earners and offers
25
+ -- "Open BLAKE's record", a link to page 3 with a valid checksum.
26
+ --
27
+ -- Like parts 41 and 42 the example creates no AI service: an administrator
28
+ -- adds one named HR_ASSISTANT under App Builder → Workspace utilities → AI
29
+ -- services (Claude, OpenAI, Gemini or an OpenAI-compatible endpoint) and
30
+ -- allows the HR application to use it.
31
+ -- =====================================================================
32
+
33
+ update meta.app set
34
+ ai_tools = $j$[
35
+ {"name": "top_earners", "type": "sql",
36
+ "description": "Active employees with their job, department and salary, highest salary first; optionally only one department (case-insensitive name, e.g. SALES).",
37
+ "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",
38
+ "parameters": {"DNAME": {"type": "string", "optional": true, "description": "A department name, e.g. SALES."}},
39
+ "max_rows": 20, "timeout_s": 10},
40
+ {"name": "open_employee", "type": "navigate",
41
+ "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\".",
42
+ "pages": [3]},
43
+ {"name": "give_raise", "type": "function",
44
+ "description": "Raise an employee's salary by a percentage. Only when the user clearly asks for it; repeat the employee and the percentage first.",
45
+ "function": "hr.give_raise",
46
+ "parameters": {"P_EMPNO": {"type": "integer", "description": "The employee number (empno)."},
47
+ "P_PCT": {"type": "number", "description": "The raise in percent, e.g. 5."}},
48
+ "authz": "MANAGER"},
49
+ {"name": "note", "type": "javascript", "action": "hr_agent_note",
50
+ "description": "Show the user a short confirmation message in the page, e.g. after a raise.",
51
+ "parameters": {"TEXT": {"type": "string", "description": "The message."}}}
52
+ ]$j$::jsonb,
53
+ ai_agents = $j$[
54
+ {"name": "HR_AGENT", "description": "Answers questions about salaries and opens employee records",
55
+ "service": "HR_ASSISTANT",
56
+ "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.",
57
+ "effort": "low", "tools": ["top_earners", "open_employee", "give_raise", "note"], "max_steps": 4, "max_tokens": 2000}
58
+ ]$j$::jsonb
59
+ where alias = 'hr';
60
+
61
+ insert into meta.page (app_id, page_no, name, title, parent_page)
62
+ select id, 46, 'HR agent', 'HR agent', 1 from meta.app where alias = 'hr';
63
+
64
+ insert into meta.region (page_id, seq, title, type, columns, template, source, condition, config)
65
+ select p.id, r.seq, r.title, r.type, r.cols, 'standard', r.source, r.cond, r.config::jsonb
66
+ from meta.page p join meta.app a on a.id = p.app_id, (values
67
+ (10, 'No AI service yet', 'static', 12,
68
+ '<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>',
69
+ 'not meta.ai_available(''HR_ASSISTANT'')', '{}'),
70
+ (20, 'Ask the HR agent', 'ai_assistant', 8, null, 'meta.ai_available(''HR_ASSISTANT'')',
71
+ $j${"agent": "HR_AGENT",
72
+ "welcome": "Hello! Ask me who earns what, e.g. who in Sales earns most. I can open an employee's record for you.",
73
+ "placeholder": "e.g. Who in Sales earns most?",
74
+ "max_turns": 20,
75
+ "error_message": "The HR agent could not answer just now. Please try again later."}$j$)
76
+ ) as r (seq, title, type, cols, source, cond, config)
77
+ where a.alias = 'hr' and p.page_no = 46;
78
+
79
+ -- the javascript tool "note": a custom event the agent raises after its answer
80
+ insert into meta.dynamic_action (page_id, seq, name, event, trigger_element, action, message)
81
+ select p.id, 10, 'Agent note', 'custom', 'hr_agent_note', 'show_success', 'The HR agent did what you asked.'
82
+ from meta.page p join meta.app a on a.id = p.app_id where a.alias = 'hr' and p.page_no = 46;
83
+
84
+ insert into meta.nav_entry (app_id, seq, label, icon, target_page)
85
+ select id, 30, 'HR agent', 'users', 46 from meta.app where alias = 'hr';
86
+
87
+ insert into meta.translation (app_id, language, source, target)
88
+ select a.id, 'nl', t.source, t.target
89
+ from meta.app a, (values
90
+ ('HR agent', 'HR-agent'),
91
+ ('Ask the HR agent', 'Vraag het de HR-agent'),
92
+ ('Hello! Ask me who earns what, e.g. who in Sales earns most. I can open an employee''s record for you.',
93
+ 'Hallo! Vraag me wie wat verdient, bijv. wie in Sales het meest verdient. Ik kan ook de gegevens van een medewerker voor je openen.'),
94
+ ('e.g. Who in Sales earns most?', 'bijv. Wie verdient het meest in Sales?')
95
+ ) as t (source, target)
96
+ where a.alias = 'hr'
97
+ on conflict do nothing;
@@ -0,0 +1,21 @@
1
+ -- =====================================================================
2
+ -- HR example, part 65: "Ask in your own words" without an AI service
3
+ -- (docs/guide/04-pages-and-regions.md, "Ask in your own words")
4
+ --
5
+ -- Page 2 "Employees": the interactive report gets a question box with the
6
+ -- built-in phrases ("ai_filter": {} names no AI service). Try
7
+ -- sum of salary by department where job is clerk
8
+ -- salary over 2500, sort by hire date, newest first
9
+ -- only clerks hired after 1981
10
+ -- bonus is 10% of salary
11
+ -- highlight salary over 4000 in red
12
+ -- Each answer becomes the report's own settings (filters, sort, group by,
13
+ -- computed columns, …), shown as chips with Edit and Remove under the box;
14
+ -- Undo goes back a step. Page 38's staff list uses the HR_ASSISTANT AI
15
+ -- service when an administrator has added it, else the same phrases.
16
+ -- =====================================================================
17
+
18
+ update meta.region r
19
+ set config = r.config || '{"ai_filter": {"placeholder": "e.g. sum of salary by department where job is clerk"}}'
20
+ from meta.page p, meta.app a
21
+ 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';