@zeyos/zx 5.6.0 → 5.7.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.
- package/CHANGELOG.md +154 -0
- package/README.md +73 -7
- package/bin/zx-css.js +328 -0
- package/dist/types/components/account-menu/account-menu.d.ts +4 -2
- package/dist/types/components/activity-list/activity-list.d.ts +14 -8
- package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
- package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
- package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
- package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
- package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
- package/dist/types/components/calendar/calendar-model.d.ts +9 -2
- package/dist/types/components/calendar/calendar.d.ts +12 -4
- package/dist/types/components/chart/chart.d.ts +25 -13
- package/dist/types/components/code-editor/code-editor.d.ts +7 -2
- package/dist/types/components/composer/composer.d.ts +206 -4
- package/dist/types/components/composer/queue.d.ts +76 -0
- package/dist/types/components/copy/copy-button.d.ts +6 -4
- package/dist/types/components/copy/copy-input.d.ts +10 -6
- package/dist/types/components/datebox/date-range-box.d.ts +33 -0
- package/dist/types/components/datebox/placeholder.d.ts +7 -0
- package/dist/types/components/dock/dock.d.ts +12 -3
- package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
- package/dist/types/components/field-upload/field-upload.d.ts +3 -2
- package/dist/types/components/file-item/file-item.d.ts +3 -2
- package/dist/types/components/file-list/file-list.d.ts +14 -8
- package/dist/types/components/filter/filter-model.d.ts +31 -1
- package/dist/types/components/filter/filter.d.ts +20 -2
- package/dist/types/components/finder/finder.d.ts +14 -6
- package/dist/types/components/flag/flag.d.ts +99 -0
- package/dist/types/components/grid/grid.d.ts +1 -1
- package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
- package/dist/types/components/launcher/launcher.d.ts +2 -0
- package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
- package/dist/types/components/number-field/number-field.d.ts +17 -6
- package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
- package/dist/types/components/prose/prose.d.ts +9 -6
- package/dist/types/components/questionnaire/conditions.d.ts +270 -0
- package/dist/types/components/questionnaire/items.d.ts +52 -30
- package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
- package/dist/types/components/rating/rating.d.ts +5 -3
- package/dist/types/components/select/country.d.ts +106 -0
- package/dist/types/components/select/field-adapter.d.ts +2 -1
- package/dist/types/components/select/locale.d.ts +102 -0
- package/dist/types/components/select/select.d.ts +41 -2
- package/dist/types/components/slider/slider.d.ts +1 -0
- package/dist/types/components/sort-control/sort-control.d.ts +7 -3
- package/dist/types/components/source-list/source-list.d.ts +7 -5
- package/dist/types/components/split-view/split-view.d.ts +5 -3
- package/dist/types/components/surface/catalog.d.ts +260 -0
- package/dist/types/components/surface/elicit.d.ts +81 -0
- package/dist/types/components/surface/mcp.d.ts +165 -0
- package/dist/types/components/surface/schema.d.ts +314 -0
- package/dist/types/components/surface/stream.d.ts +118 -0
- package/dist/types/components/surface/surface.d.ts +718 -0
- package/dist/types/components/surface/text.d.ts +277 -0
- package/dist/types/components/surface/validate.d.ts +339 -0
- package/dist/types/components/table/table.d.ts +55 -3
- package/dist/types/components/table/window.d.ts +203 -0
- package/dist/types/components/toolbar/toolbar.d.ts +10 -6
- package/dist/types/components/tooltip/tooltip.d.ts +2 -2
- package/dist/types/components/tree/tree.d.ts +20 -13
- package/dist/types/core/component.d.ts +10 -0
- package/dist/types/core/date.d.ts +8 -1
- package/dist/types/core/dom.d.ts +1 -0
- package/dist/types/core/http.d.ts +10 -0
- package/dist/types/core/i18n.d.ts +38 -0
- package/dist/types/core/messages.d.ts +344 -1
- package/dist/types/core/storage.d.ts +7 -2
- package/dist/types/elements/define.d.ts +21 -46
- package/dist/types/elements/definitions.d.ts +147 -0
- package/dist/types/elements/kit.d.ts +7 -0
- package/dist/types/elements/reflect.d.ts +6 -3
- package/dist/types/index.d.ts +10 -1
- package/dist/types/internal/date-locale.d.ts +7 -0
- package/dist/types/internal/json-patch.d.ts +146 -0
- package/dist/types/locales/de.d.ts +13 -0
- package/dist/types/locales/en.d.ts +2 -0
- package/dist/types/locales/index.d.ts +823 -0
- package/dist/types/zeyos/view.d.ts +8 -1
- package/dist/zx-zeyos.esm.js +16802 -15180
- package/dist/zx-zeyos.esm.min.js +5 -5
- package/dist/zx.core.css +1276 -0
- package/dist/zx.core.min.css +1 -0
- package/dist/zx.css +498 -134
- package/dist/zx.esm.js +40778 -29654
- package/dist/zx.esm.min.js +36 -23
- package/dist/zx.global.js +40778 -29654
- package/dist/zx.global.min.js +36 -23
- package/dist/zx.layered.css +17302 -0
- package/dist/zx.layered.min.css +1 -0
- package/dist/zx.min.css +1 -1
- package/docs/agent-catalog.json +12501 -0
- package/docs/agent-surfaces.md +340 -0
- package/docs/api.json +851 -121
- package/docs/llms.md +1018 -71
- package/docs/llms.txt +30 -9
- package/package.json +29 -6
- package/src/components/account-menu/account-menu.js +6 -3
- package/src/components/activity-item/activity-item.js +2 -1
- package/src/components/activity-list/activity-list.js +16 -10
- package/src/components/agent-thread/ag-ui.js +1439 -0
- package/src/components/agent-thread/agent-thread.js +359 -54
- package/src/components/agent-thread/ui-message-stream.js +1281 -0
- package/src/components/app-sidebar/app-sidebar.js +18 -8
- package/src/components/approval-card/approval-card.js +3 -2
- package/src/components/block-view/block-view.js +7 -6
- package/src/components/breadcrumb/breadcrumb.js +8 -5
- package/src/components/calendar/calendar-model.js +8 -2
- package/src/components/calendar/calendar.js +53 -18
- package/src/components/chart/chart.js +54 -23
- package/src/components/code-editor/code-editor.js +45 -8
- package/src/components/code-editor/field-adapter.js +1 -1
- package/src/components/composer/composer.css +80 -1
- package/src/components/composer/composer.js +390 -16
- package/src/components/composer/queue.js +78 -0
- package/src/components/context-menu/context-menu.js +12 -1
- package/src/components/copy/copy-button.js +9 -7
- package/src/components/copy/copy-input.js +10 -6
- package/src/components/date-picker/date-picker.js +2 -1
- package/src/components/date-picker/date-range-picker.js +8 -7
- package/src/components/datebox/date-range-box.js +3 -9
- package/src/components/datebox/datebox.js +18 -21
- package/src/components/datebox/placeholder.js +18 -0
- package/src/components/dialog/dialog.js +1 -1
- package/src/components/dock/dock.js +34 -13
- package/src/components/entity-ref/entity-ref.js +16 -5
- package/src/components/field-upload/field-upload.js +81 -38
- package/src/components/file-item/file-item.js +70 -40
- package/src/components/file-list/file-list.js +15 -9
- package/src/components/filter/filter-model.js +46 -8
- package/src/components/filter/filter.css +3 -3
- package/src/components/filter/filter.js +29 -10
- package/src/components/filter-panel/filter-panel.js +13 -5
- package/src/components/finder/finder.js +50 -26
- package/src/components/flag/flag.css +40 -0
- package/src/components/flag/flag.js +177 -0
- package/src/components/form/form.js +1 -1
- package/src/components/grid/grid.js +22 -8
- package/src/components/kanban-view/kanban-view.js +51 -81
- package/src/components/launcher/launcher.js +17 -2
- package/src/components/list-toolbar/list-toolbar.js +2 -1
- package/src/components/master-panel/master-panel.js +1 -1
- package/src/components/menu-button/menu-button.js +4 -0
- package/src/components/message/message.js +3 -0
- package/src/components/multi-value-editor/multi-value-editor.js +10 -9
- package/src/components/navigation-bar/navigation-bar.js +3 -3
- package/src/components/number-field/number-field.js +29 -13
- package/src/components/prompt-starters/prompt-starters.css +91 -0
- package/src/components/prompt-starters/prompt-starters.js +206 -0
- package/src/components/prose/prose.js +14 -10
- package/src/components/questionnaire/conditions.js +666 -0
- package/src/components/questionnaire/items.js +150 -41
- package/src/components/questionnaire/questionnaire.js +126 -32
- package/src/components/rating/rating.js +5 -4
- package/src/components/run-status/run-status.js +2 -2
- package/src/components/select/country.js +136 -0
- package/src/components/select/field-adapter.js +7 -2
- package/src/components/select/locale.js +219 -0
- package/src/components/select/select.css +20 -22
- package/src/components/select/select.js +94 -12
- package/src/components/sheet/sheet-stack.js +10 -1
- package/src/components/slider/slider.js +7 -2
- package/src/components/sort-control/sort-control.js +15 -5
- package/src/components/source-list/source-list.js +7 -4
- package/src/components/split-view/split-view.js +5 -3
- package/src/components/surface/catalog.js +1334 -0
- package/src/components/surface/elicit.js +107 -0
- package/src/components/surface/mcp.js +243 -0
- package/src/components/surface/schema.js +644 -0
- package/src/components/surface/stream.js +245 -0
- package/src/components/surface/surface.css +308 -0
- package/src/components/surface/surface.js +2291 -0
- package/src/components/surface/text.js +513 -0
- package/src/components/surface/validate.js +2218 -0
- package/src/components/tabbox/tabbox.js +9 -0
- package/src/components/table/table.css +63 -3
- package/src/components/table/table.js +167 -28
- package/src/components/table/window.js +317 -0
- package/src/components/toolbar/toolbar.js +12 -7
- package/src/components/tooltip/tooltip.css +2 -3
- package/src/components/tooltip/tooltip.js +32 -5
- package/src/components/tree/tree.js +53 -23
- package/src/core/component.js +25 -1
- package/src/core/date.js +62 -16
- package/src/core/dom.js +22 -2
- package/src/core/format.js +15 -13
- package/src/core/http.js +29 -20
- package/src/core/i18n.js +83 -10
- package/src/core/keyboard.js +79 -8
- package/src/core/messages.js +376 -2
- package/src/core/overlay-host.js +1 -0
- package/src/core/storage.js +59 -6
- package/src/elements/define.js +178 -130
- package/src/elements/definitions.js +229 -0
- package/src/elements/kit.js +444 -0
- package/src/elements/reflect.js +8 -3
- package/src/index.js +10 -1
- package/src/internal/date-locale.js +11 -0
- package/src/internal/json-patch.js +405 -0
- package/src/locales/de.js +911 -0
- package/src/locales/en.js +2 -0
- package/src/locales/index.js +7 -0
- package/src/zeyos/calendar.js +2 -1
- package/src/zeyos/form.js +2 -1
- package/src/zeyos/launcher.js +7 -6
- package/src/zeyos/module-bar.js +2 -1
- package/src/zeyos/schema.js +37 -23
- package/src/zeyos/select.js +4 -3
- package/src/zeyos/table.js +2 -13
- package/src/zeyos/view.js +57 -17
- package/styles/core.css +11 -0
- package/styles/tokens/semantic.css +1 -0
- package/styles/zeyos.css +2 -0
- package/styles/zx.css +4 -8
- package/styles/zx.layered.css +1 -0
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* `elicit()`: a form-mode elicitation request — a message and a restricted JSON Schema — drawn as
|
|
4
|
+
* an `ask` surface, answered as `accept`, `decline` or `cancel`. It is the renderer a client of the
|
|
5
|
+
* MCP protocol's form-mode elicitation needs; transport stays with the application.
|
|
6
|
+
*/
|
|
7
|
+
import { uid } from '../../core/util.js';
|
|
8
|
+
import { LIMITS } from './catalog.js';
|
|
9
|
+
import { unsupported } from './schema.js';
|
|
10
|
+
import { openSurface } from './surface.js';
|
|
11
|
+
import { messageResolver, plainInline } from './text.js';
|
|
12
|
+
|
|
13
|
+
/** @typedef {import('./schema.js').InputSchema} InputSchema */
|
|
14
|
+
/** @typedef {import('./surface.js').OpenSurfaceOptions} OpenSurfaceOptions */
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* A form-mode elicitation request.
|
|
18
|
+
* @typedef {Object} ElicitRequest
|
|
19
|
+
* @property {string} message What is asked, and why.
|
|
20
|
+
* @property {InputSchema} requestedSchema One flat object of `string`, `number`, `integer`,
|
|
21
|
+
* `boolean` and multiple-choice properties.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* The person's answer.
|
|
26
|
+
* @typedef {Object} ElicitResult
|
|
27
|
+
* @property {'accept'|'decline'|'cancel'} action `accept` with the content, `decline` when the
|
|
28
|
+
* person refused, `cancel` when they closed the form.
|
|
29
|
+
* @property {Record<string, string|number|boolean|string[]>} [content] The submitted values,
|
|
30
|
+
* checked against the schema; only with `accept`.
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Options of `elicit()`: where the form goes, who asks, and the Surface's own options.
|
|
35
|
+
* @typedef {Omit<OpenSurfaceOptions, 'document'> & {
|
|
36
|
+
* title?: string,
|
|
37
|
+
* author?: string,
|
|
38
|
+
* lang?: string,
|
|
39
|
+
* msg?: Record<string, string>|Record<string, Record<string, string>>
|
|
40
|
+
* }} ElicitOptions
|
|
41
|
+
*/
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The `ask` surface `elicit()` draws for a request: the server's message as plain text — its
|
|
45
|
+
* characters drawn as given, never read as markup — and the form, with Submit and Decline. Labels
|
|
46
|
+
* resolve as a Surface's own do: `options.msg` for the active language, then its flat entries, the
|
|
47
|
+
* host translator, and English. Pure: it draws nothing.
|
|
48
|
+
* @param {ElicitRequest} request
|
|
49
|
+
* @param {ElicitOptions} [options] `title`, `author`, `msg` and `lang` are read.
|
|
50
|
+
* @returns {import('./validate.js').SurfaceDocument}
|
|
51
|
+
* @throws {TypeError} When the schema lies outside the subset, naming what is unsupported.
|
|
52
|
+
*/
|
|
53
|
+
export function elicitDocument(request, options = {}) {
|
|
54
|
+
const message = typeof request?.message === 'string' ? request.message : '';
|
|
55
|
+
const schema = request?.requestedSchema;
|
|
56
|
+
const problems = unsupported(schema);
|
|
57
|
+
if (problems.length) {
|
|
58
|
+
throw new TypeError(`The requested schema is not supported: ${problems.map((problem) => (problem.path ? `${problem.path}: ${problem.message}` : problem.message)).join('; ')}`);
|
|
59
|
+
}
|
|
60
|
+
const { title, author = 'server' } = options;
|
|
61
|
+
const lang = /** @type {any} */ (options).lang ?? /** @type {any} */ (options).language;
|
|
62
|
+
const text = messageResolver(/** @type {Record<string, any>|undefined} */ (options.msg), typeof lang === 'string' ? lang : undefined);
|
|
63
|
+
const short = message.trim() && message.length <= LIMITS.label;
|
|
64
|
+
/** @type {Array<Record<string, unknown>>} */
|
|
65
|
+
const nodes = [];
|
|
66
|
+
if (message.trim() && (title || !short)) nodes.push({ id: 'message', type: 'text', text: plainInline(message, LIMITS.string) });
|
|
67
|
+
nodes.push({ id: 'form', type: 'fields', schema: structuredClone(schema) });
|
|
68
|
+
return /** @type {any} */ ({
|
|
69
|
+
zx: 'surface/1',
|
|
70
|
+
surface: uid('elicit'),
|
|
71
|
+
intent: 'ask',
|
|
72
|
+
// A title is drawn as text, never as markup.
|
|
73
|
+
title: (title ?? (short ? message : text('surface.requested'))).slice(0, LIMITS.label),
|
|
74
|
+
author,
|
|
75
|
+
root: nodes.map((node) => node.id),
|
|
76
|
+
nodes,
|
|
77
|
+
actions: [
|
|
78
|
+
{ id: 'submit', label: text('surface.submit'), kind: 'primary' },
|
|
79
|
+
{ id: 'reject', label: text('surface.decline') }
|
|
80
|
+
]
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Asks the person for the values a request names, in a Dialog — or inline in `options.target` —
|
|
86
|
+
* and resolves with their answer: Submit resolves `accept` with the values checked against the
|
|
87
|
+
* schema, Decline resolves `decline`, and Escape or closing resolves `cancel`. The surface is
|
|
88
|
+
* `elicitDocument()`'s. `options.signal` withdraws the request: when it aborts — or if it already
|
|
89
|
+
* has — the form is cancelled (a dialog closes, an inline form stays as its receipt) and the
|
|
90
|
+
* promise resolves `cancel`.
|
|
91
|
+
* @param {ElicitRequest} request
|
|
92
|
+
* @param {ElicitOptions} [options]
|
|
93
|
+
* @returns {Promise<ElicitResult>}
|
|
94
|
+
* @throws {TypeError} Rejects when the schema lies outside the subset, naming what is unsupported.
|
|
95
|
+
*/
|
|
96
|
+
export async function elicit(request, options = {}) {
|
|
97
|
+
const document = elicitDocument(request, options);
|
|
98
|
+
const { title, author, target = null, placement, ...rest } = options;
|
|
99
|
+
const reply = await openSurface(document, {
|
|
100
|
+
...rest,
|
|
101
|
+
target,
|
|
102
|
+
placement: placement ?? (target ? 'inline' : 'dialog')
|
|
103
|
+
});
|
|
104
|
+
if (reply.action === 'submit') return { action: 'accept', content: /** @type {any} */ (reply.values) };
|
|
105
|
+
if (reply.action === 'reject') return { action: 'decline' };
|
|
106
|
+
return { action: 'cancel' };
|
|
107
|
+
}
|
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* `elicitationHandler()`: answers MCP elicitation requests with surfaces.
|
|
4
|
+
*
|
|
5
|
+
* In MCP, a server asks the client for input in one of two modes. In form mode it sends a message
|
|
6
|
+
* and a restricted JSON Schema, and the person fills a form. In URL mode it sends a message and an
|
|
7
|
+
* address, and the person is sent to that page. The handler takes the request's `params` already
|
|
8
|
+
* parsed, whether they came as an `elicitation/create` request or as an `inputRequests` entry of
|
|
9
|
+
* an `input_required` result, and resolves the result the client sends back. The application owns
|
|
10
|
+
* the MCP client: transport, sessions and authentication stay with it.
|
|
11
|
+
*/
|
|
12
|
+
import { uid } from '../../core/util.js';
|
|
13
|
+
import { LIMITS } from './catalog.js';
|
|
14
|
+
import { elicit } from './elicit.js';
|
|
15
|
+
import { openSurface } from './surface.js';
|
|
16
|
+
import { messageResolver, plainInline } from './text.js';
|
|
17
|
+
import { normaliseLink } from './validate.js';
|
|
18
|
+
|
|
19
|
+
/** @typedef {import('./elicit.js').ElicitResult} ElicitResult */
|
|
20
|
+
/** @typedef {import('./schema.js').InputSchema} InputSchema */
|
|
21
|
+
/** @typedef {import('./surface.js').SurfaceReply} SurfaceReply */
|
|
22
|
+
|
|
23
|
+
/** The MCP revision whose elicitation the handler implements. */
|
|
24
|
+
export const MCP_ELICITATION_VERSION = '2026-07-28';
|
|
25
|
+
|
|
26
|
+
/** The author key every elicitation surface is drawn under; its name is the server's. */
|
|
27
|
+
const AUTHOR = 'mcp-server';
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* An elicitation request's `params`. Form mode is the default when `mode` is absent; fields a mode
|
|
31
|
+
* does not use, such as the `elicitationId` of earlier revisions, are ignored.
|
|
32
|
+
* @typedef {Object} ElicitationParams
|
|
33
|
+
* @property {'form'|'url'} [mode] How the server asks.
|
|
34
|
+
* @property {string} message What is asked, and why.
|
|
35
|
+
* @property {InputSchema} [requestedSchema] Form mode: one flat object of primitive and
|
|
36
|
+
* multiple-choice properties.
|
|
37
|
+
* @property {string} [url] URL mode: the page the person is sent to, `https:` only.
|
|
38
|
+
* @property {string} [elicitationId] Sent by servers of the 2025-11-25 revision; ignored.
|
|
39
|
+
*/
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Options of `elicitationHandler()`.
|
|
43
|
+
* @typedef {Object} ElicitationHandlerOptions
|
|
44
|
+
* @property {string} serverName The name of the server that asks, as the client knows it; shown as
|
|
45
|
+
* "Asked by <server>". Required: the person must always see who asks.
|
|
46
|
+
* @property {Record<string, {name: string}>} [authors={}] Display names by key; when it lists
|
|
47
|
+
* `serverName`, that entry's name is shown instead.
|
|
48
|
+
* @property {Element|string|null} [target=null] Where the surface goes inline; a Dialog without one.
|
|
49
|
+
* @property {(url: string) => boolean|void} [open] Opens the page in URL mode, after the person
|
|
50
|
+
* agreed. It receives the normalised address and must open it in a new browsing context that
|
|
51
|
+
* cannot reach the application; returning `false` or throwing means it was not opened, and the
|
|
52
|
+
* request answers `cancel`. The default opens a new tab with `noopener` and `noreferrer`.
|
|
53
|
+
* @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
|
|
54
|
+
* messages, flat or by language: the `mcp.*` keys, and the `surface.*` keys of the form.
|
|
55
|
+
*/
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* What the client knows about one request beyond its `params`.
|
|
59
|
+
* @typedef {Object} ElicitationContext
|
|
60
|
+
* @property {AbortSignal|null} [signal] Withdraws the request — the server cancelled it, the call
|
|
61
|
+
* timed out, the session closed: the surface is cancelled with the reason `stopped` (a dialog
|
|
62
|
+
* closes, an inline surface stays as its receipt), nothing opens, and the request resolves
|
|
63
|
+
* `cancel`. Already aborted, it resolves `cancel` without drawing anything. Abort it as well
|
|
64
|
+
* when the application removes an inline `target`, or the request stays pending.
|
|
65
|
+
*/
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* A URL-mode address, checked and normalised.
|
|
69
|
+
* @typedef {Object} ElicitationUrl
|
|
70
|
+
* @property {string} href The normalised address: what is shown in full and what is opened.
|
|
71
|
+
* @property {string} host The host, with its port when it has one, as the browser will reach it.
|
|
72
|
+
* @property {boolean} international Whether the host holds an internationalised (Punycode) label,
|
|
73
|
+
* which can imitate another name.
|
|
74
|
+
*/
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Creates the function an MCP client installs to answer elicitation requests. Form mode draws an
|
|
78
|
+
* `ask` surface through `elicit()`. URL mode draws a `confirm` surface naming the page's host,
|
|
79
|
+
* emphasised, and its full address; nothing is loaded and nothing opens until the person agrees.
|
|
80
|
+
* Open the page opens it in a new browsing context, without opener or referrer, and answers
|
|
81
|
+
* `accept`; Decline answers `decline`; Cancel, Escape or closing the dialog answers `cancel`.
|
|
82
|
+
* @param {ElicitationHandlerOptions} options
|
|
83
|
+
* @returns {(params: ElicitationParams, context?: ElicitationContext) => Promise<ElicitResult>}
|
|
84
|
+
* Resolves the result to send back;
|
|
85
|
+
* rejects with a `TypeError` — so the client can answer the server with an error — for a request
|
|
86
|
+
* that is not an object, an unknown `mode`, a `message` that is not text, a schema outside the
|
|
87
|
+
* supported subset, or an address that is not a valid `https:` URL.
|
|
88
|
+
* @throws {TypeError} When `serverName` is missing.
|
|
89
|
+
*/
|
|
90
|
+
export function elicitationHandler(options) {
|
|
91
|
+
const serverName = typeof options?.serverName === 'string' ? options.serverName.trim() : '';
|
|
92
|
+
if (!serverName) throw new TypeError('elicitationHandler() needs the "serverName" of the server that asks');
|
|
93
|
+
const authors = options.authors && typeof options.authors === 'object' ? options.authors : {};
|
|
94
|
+
const listed = Object.hasOwn(authors, serverName) ? authors[serverName]?.name : undefined;
|
|
95
|
+
const shown = (typeof listed === 'string' && listed.trim() ? listed : serverName).slice(0, LIMITS.label);
|
|
96
|
+
const target = options.target ?? null;
|
|
97
|
+
const open = typeof options.open === 'function' ? options.open : openPage;
|
|
98
|
+
const own = options.msg && typeof options.msg === 'object' ? options.msg : null;
|
|
99
|
+
const text = messageResolver(own);
|
|
100
|
+
|
|
101
|
+
return async (params, context = {}) => {
|
|
102
|
+
if (!params || typeof params !== 'object' || Array.isArray(params)) {
|
|
103
|
+
throw new TypeError('An elicitation request is an object');
|
|
104
|
+
}
|
|
105
|
+
const mode = params.mode;
|
|
106
|
+
if (mode !== undefined && mode !== 'form' && mode !== 'url') {
|
|
107
|
+
throw new TypeError(`The elicitation mode ${JSON.stringify(mode)} is not supported; use "form" or "url"`);
|
|
108
|
+
}
|
|
109
|
+
if (typeof params.message !== 'string') throw new TypeError('An elicitation request needs a "message"');
|
|
110
|
+
// Read on every request, so a language switched in between is honoured.
|
|
111
|
+
const msg = withByline(own, text('mcp.askedBy'));
|
|
112
|
+
const signal = context?.signal ?? null;
|
|
113
|
+
const surface = { target, authors: { [AUTHOR]: { name: shown } }, msg, signal };
|
|
114
|
+
if (mode === 'url') return askToOpen(params.message, elicitationUrl(params.url), surface, open, text);
|
|
115
|
+
return elicit({ message: params.message, requestedSchema: /** @type {InputSchema} */ (params.requestedSchema) },
|
|
116
|
+
{ ...surface, author: AUTHOR });
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Checks a URL-mode address the way surface links are checked, and normalises it: an absolute
|
|
122
|
+
* `https://` address in lower case, without credentials, spaces, backslashes, control or invisible
|
|
123
|
+
* formatting characters, at most 2000 characters. The address returned is the parsed one, so the
|
|
124
|
+
* host shown and the page opened come from the same string.
|
|
125
|
+
* @param {unknown} value The request's `url`.
|
|
126
|
+
* @returns {ElicitationUrl}
|
|
127
|
+
* @throws {TypeError} When the address is missing or refused.
|
|
128
|
+
*/
|
|
129
|
+
export function elicitationUrl(value) {
|
|
130
|
+
if (value === undefined) throw new TypeError('The elicitation URL is refused: a URL-mode request needs a "url"');
|
|
131
|
+
const link = normaliseLink(value);
|
|
132
|
+
if (link.href === null) throw new TypeError(`The elicitation URL is refused: ${link.problem}`);
|
|
133
|
+
const url = new URL(link.href);
|
|
134
|
+
return { href: link.href, host: url.host, international: url.hostname.split('.').some((label) => label.startsWith('xn--')) };
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The `confirm` surface that asks before a URL-mode page opens: the server's message as plain
|
|
139
|
+
* text, the host emphasised, the full address, a warning for an internationalised host, and what
|
|
140
|
+
* opening does. No part of it is a link.
|
|
141
|
+
* @param {string} message The server's message.
|
|
142
|
+
* @param {ElicitationUrl} url From `elicitationUrl()`.
|
|
143
|
+
* @param {(key: string, ...args: unknown[]) => string} [text] Resolves the `mcp.*` messages;
|
|
144
|
+
* English by default.
|
|
145
|
+
* @returns {import('./validate.js').SurfaceDocument}
|
|
146
|
+
*/
|
|
147
|
+
export function urlConsentDocument(message, url, text = messageResolver(null)) {
|
|
148
|
+
/** @type {Array<Record<string, unknown>>} */
|
|
149
|
+
const nodes = [];
|
|
150
|
+
if (message.trim()) nodes.push({ id: 'message', type: 'text', text: plainInline(message, LIMITS.string) });
|
|
151
|
+
nodes.push({ id: 'host', type: 'text', text: around(text, 'mcp.urlHost', `**${plainInline(url.host)}**`) });
|
|
152
|
+
nodes.push({ id: 'address', type: 'text', text: around(text, 'mcp.urlAddress', plainInline(url.href)) });
|
|
153
|
+
if (url.international) nodes.push({ id: 'international', type: 'callout', tone: 'warning', text: text('mcp.urlInternational') });
|
|
154
|
+
nodes.push({ id: 'note', type: 'text', text: text('mcp.urlNote') });
|
|
155
|
+
return /** @type {any} */ ({
|
|
156
|
+
zx: 'surface/1',
|
|
157
|
+
surface: uid('elicit-url'),
|
|
158
|
+
intent: 'confirm',
|
|
159
|
+
title: text('mcp.urlTitle').slice(0, LIMITS.label),
|
|
160
|
+
author: AUTHOR,
|
|
161
|
+
root: nodes.map((node) => node.id),
|
|
162
|
+
nodes,
|
|
163
|
+
actions: [
|
|
164
|
+
{ id: 'confirm', label: text('mcp.urlOpen').slice(0, LIMITS.label), kind: 'primary' },
|
|
165
|
+
{ id: 'reject', label: text('mcp.decline').slice(0, LIMITS.label) }
|
|
166
|
+
]
|
|
167
|
+
});
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/* ------------------------------------------------------------------ module helpers -- */
|
|
171
|
+
|
|
172
|
+
/** Stands in for a server's value while a message is resolved. */
|
|
173
|
+
const PLACEHOLDER = '\u0000';
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* A message around a value of the server's, which is put in afterwards: a message's placeholders
|
|
177
|
+
* are read in what it is given too, and an address may hold what looks like one (`/%a%/`).
|
|
178
|
+
* @param {(key: string, ...args: unknown[]) => string} text @param {string} key @param {string} value
|
|
179
|
+
* @returns {string}
|
|
180
|
+
*/
|
|
181
|
+
function around(text, key, value) {
|
|
182
|
+
const message = text(key, PLACEHOLDER);
|
|
183
|
+
return message.includes(PLACEHOLDER) ? message.replace(PLACEHOLDER, () => value) : `${message} ${value}`;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Asks before opening a URL-mode page, and opens it in the click that agreed.
|
|
188
|
+
* @param {string} message @param {ElicitationUrl} url
|
|
189
|
+
* @param {{target: Element|string|null, authors: Record<string, {name: string}>, msg: Record<string, any>, signal: AbortSignal|null}} surface
|
|
190
|
+
* @param {(url: string) => boolean|void} open
|
|
191
|
+
* @param {(key: string, ...args: unknown[]) => string} text
|
|
192
|
+
* @returns {Promise<ElicitResult>}
|
|
193
|
+
*/
|
|
194
|
+
async function askToOpen(message, url, surface, open, text) {
|
|
195
|
+
let opened = false;
|
|
196
|
+
const reply = await openSurface(urlConsentDocument(message, url, text), {
|
|
197
|
+
...surface,
|
|
198
|
+
placement: surface.target ? 'inline' : 'dialog',
|
|
199
|
+
// The page opens inside the person's click, before the dialog closes, so a browser that
|
|
200
|
+
// blocks pages opened without a gesture lets it through.
|
|
201
|
+
onopen: (drawn) => drawn.on('reply', (event) => {
|
|
202
|
+
if (/** @type {CustomEvent<{reply: SurfaceReply}>} */ (event).detail.reply.action !== 'confirm') return;
|
|
203
|
+
try {
|
|
204
|
+
opened = open(url.href) !== false;
|
|
205
|
+
} catch {
|
|
206
|
+
opened = false;
|
|
207
|
+
}
|
|
208
|
+
})
|
|
209
|
+
});
|
|
210
|
+
if (reply.action === 'confirm') return { action: opened ? 'accept' : 'cancel' };
|
|
211
|
+
if (reply.action === 'reject') return { action: 'decline' };
|
|
212
|
+
return { action: 'cancel' };
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* The default opener: a new top-level browsing context that gets neither a handle on this page
|
|
217
|
+
* nor its address.
|
|
218
|
+
* @param {string} href
|
|
219
|
+
* @returns {boolean}
|
|
220
|
+
*/
|
|
221
|
+
function openPage(href) {
|
|
222
|
+
const view = globalThis.window;
|
|
223
|
+
if (typeof view?.open !== 'function') return false;
|
|
224
|
+
// With "noopener" the browser returns no handle, so a blocked window cannot be told apart.
|
|
225
|
+
view.open(href, '_blank', 'noopener,noreferrer');
|
|
226
|
+
return true;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* The `msg` a surface gets: the application's, with the byline saying who asks — in every
|
|
231
|
+
* language table it holds, so none of them says "Composed by".
|
|
232
|
+
* @param {Record<string, any>|null} own @param {string} byline
|
|
233
|
+
* @returns {Record<string, any>}
|
|
234
|
+
*/
|
|
235
|
+
function withByline(own, byline) {
|
|
236
|
+
/** @type {Record<string, any>} */
|
|
237
|
+
const msg = {};
|
|
238
|
+
for (const [key, value] of Object.entries(own ?? {})) {
|
|
239
|
+
msg[key] = value && typeof value === 'object' ? { ...value, 'surface.byline': byline } : value;
|
|
240
|
+
}
|
|
241
|
+
msg['surface.byline'] = byline;
|
|
242
|
+
return msg;
|
|
243
|
+
}
|