@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,260 @@
|
|
|
1
|
+
/** The version a `begin` operation and a document carry. */
|
|
2
|
+
export declare const SURFACE_VERSION = "surface/1";
|
|
3
|
+
/** The version every reply carries. */
|
|
4
|
+
export declare const REPLY_VERSION = "reply/1";
|
|
5
|
+
/** The limits of one surface. Anything over a limit is dropped and reported. */
|
|
6
|
+
export declare const LIMITS: Readonly<{
|
|
7
|
+
/** Nodes per surface. */
|
|
8
|
+
nodes: 400;
|
|
9
|
+
/** Depth of the node tree, counting the root's children as 1. */
|
|
10
|
+
depth: 12;
|
|
11
|
+
/** Characters per string. */
|
|
12
|
+
string: 20000;
|
|
13
|
+
/** Rows per table or diff, and entries per list or other array. */
|
|
14
|
+
rows: 1000;
|
|
15
|
+
/** Input schema properties per surface. */
|
|
16
|
+
fields: 50;
|
|
17
|
+
/** Choices per choice node or schema property. */
|
|
18
|
+
choices: 64;
|
|
19
|
+
/** Actions per surface. */
|
|
20
|
+
actions: 8;
|
|
21
|
+
/** Characters of the surface's data, written as JSON. */
|
|
22
|
+
data: 1000000;
|
|
23
|
+
/** Nesting of a `visible`, `when` or `if` condition. */
|
|
24
|
+
condition: 4;
|
|
25
|
+
/** Nesting of any JSON value inside one operation, counting the operation as 1. */
|
|
26
|
+
value: 32;
|
|
27
|
+
/** Columns per table. */
|
|
28
|
+
columns: 50;
|
|
29
|
+
/** Table cells across all tables of a surface; a `$data` binding counts each time it is used. */
|
|
30
|
+
cells: 100000;
|
|
31
|
+
/** Datasets per chart. */
|
|
32
|
+
datasets: 12;
|
|
33
|
+
/** Steps per questionnaire. */
|
|
34
|
+
steps: 50;
|
|
35
|
+
/** Sources per surface. */
|
|
36
|
+
sources: 50;
|
|
37
|
+
/** Characters of a title, label or other short text. */
|
|
38
|
+
label: 200;
|
|
39
|
+
/** Characters of a description. */
|
|
40
|
+
description: 2000;
|
|
41
|
+
/** Characters of an id, a name, an author or a tool. */
|
|
42
|
+
name: 64;
|
|
43
|
+
/** Characters of a link address. */
|
|
44
|
+
href: 2000;
|
|
45
|
+
}>;
|
|
46
|
+
/** The six intents, in the order the guide presents them. */
|
|
47
|
+
export declare const INTENTS: readonly SurfaceIntent[];
|
|
48
|
+
/** Where a surface asks to be placed. */
|
|
49
|
+
export declare const PLACEMENTS: readonly SurfacePlacement[];
|
|
50
|
+
/** Action ids kept for closing a surface. An action of the surface's own cannot use them. */
|
|
51
|
+
export declare const RESERVED_ACTIONS: readonly string[];
|
|
52
|
+
/** What an id looks like: a node, an action, a row or a surface. Never `constructor` or `prototype`. */
|
|
53
|
+
export declare const ID_PATTERN = "^(?!(?:constructor|prototype)$)[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$";
|
|
54
|
+
/**
|
|
55
|
+
* What an input name, a column id, a row key or a step name looks like: it becomes a key of the
|
|
56
|
+
* reply's `values` or of a row, so `__proto__`, `constructor` and `prototype` are excluded.
|
|
57
|
+
*/
|
|
58
|
+
export declare const NAME_PATTERN = "^(?!(?:__proto__|constructor|prototype)$)[A-Za-z_][A-Za-z0-9_.-]{0,63}$";
|
|
59
|
+
/**
|
|
60
|
+
* What a link address looks like: `https://` in lower case, a host without credentials, and no
|
|
61
|
+
* whitespace, control, backslash or invisible format characters anywhere. The validator applies
|
|
62
|
+
* the same pattern, then parses the address.
|
|
63
|
+
*/
|
|
64
|
+
export declare const HREF_PATTERN: string;
|
|
65
|
+
/** What an icon name looks like. */
|
|
66
|
+
export declare const ICON_PATTERN = "^[a-z0-9][a-z0-9-]{0,39}$";
|
|
67
|
+
/** Keys refused anywhere, at any depth. */
|
|
68
|
+
export declare const FORBIDDEN_KEYS: readonly string[];
|
|
69
|
+
export type SurfaceIntent = 'show' | 'ask' | 'choose' | 'confirm' | 'review' | 'questionnaire';
|
|
70
|
+
export type SurfacePlacement = 'inline' | 'sheet' | 'dialog';
|
|
71
|
+
export type CatalogType = 'string' | 'integer' | 'number' | 'boolean' | 'number|string' | 'string[]' | 'Href' | 'Ref' | 'Column[]' | 'Row[]' | 'Figure[]' | 'ChartData' | 'Choice[]' | 'DiffRow[]' | 'Schema' | 'Step[]';
|
|
72
|
+
export type CatalogProp = {
|
|
73
|
+
/**
|
|
74
|
+
* What the value is.
|
|
75
|
+
*/
|
|
76
|
+
type: CatalogType;
|
|
77
|
+
/**
|
|
78
|
+
* The values allowed.
|
|
79
|
+
*/
|
|
80
|
+
enum?: ReadonlyArray<string | number>;
|
|
81
|
+
/**
|
|
82
|
+
* Most characters of a string, or entries of a list.
|
|
83
|
+
*/
|
|
84
|
+
max?: number;
|
|
85
|
+
/**
|
|
86
|
+
* Whether the node needs it to render.
|
|
87
|
+
*/
|
|
88
|
+
required?: boolean;
|
|
89
|
+
/**
|
|
90
|
+
* The component option the property maps to: an option name, or
|
|
91
|
+
* `<option>[].<member>` for a member of a list option's entries. `null` when the surface itself
|
|
92
|
+
* consumes it (an input's `name`, a link's text and address).
|
|
93
|
+
*/
|
|
94
|
+
option: string | null;
|
|
95
|
+
};
|
|
96
|
+
export type CatalogNode = {
|
|
97
|
+
/**
|
|
98
|
+
* The node type.
|
|
99
|
+
*/
|
|
100
|
+
type: string;
|
|
101
|
+
/**
|
|
102
|
+
* The component that draws it, as `docs/api.json` names it;
|
|
103
|
+
* `null` for a node the surface draws itself.
|
|
104
|
+
*/
|
|
105
|
+
component: string | null;
|
|
106
|
+
/**
|
|
107
|
+
* The one intent the node may appear in.
|
|
108
|
+
*/
|
|
109
|
+
intentOnly?: SurfaceIntent;
|
|
110
|
+
/**
|
|
111
|
+
* Whether it lays out `children`.
|
|
112
|
+
*/
|
|
113
|
+
children: boolean;
|
|
114
|
+
/**
|
|
115
|
+
* Whether its value lands in the reply's `values`.
|
|
116
|
+
*/
|
|
117
|
+
input: boolean;
|
|
118
|
+
/**
|
|
119
|
+
* Its properties.
|
|
120
|
+
*/
|
|
121
|
+
props: Readonly<Record<string, CatalogProp>>;
|
|
122
|
+
};
|
|
123
|
+
export type CatalogIntent = {
|
|
124
|
+
/**
|
|
125
|
+
* The intent.
|
|
126
|
+
*/
|
|
127
|
+
intent: SurfaceIntent;
|
|
128
|
+
/**
|
|
129
|
+
* Node types of which the surface needs at least one;
|
|
130
|
+
* empty when it needs none.
|
|
131
|
+
*/
|
|
132
|
+
requires: ReadonlyArray<string>;
|
|
133
|
+
/**
|
|
134
|
+
* The default actions, by label.
|
|
135
|
+
*/
|
|
136
|
+
actions: ReadonlyArray<string>;
|
|
137
|
+
/**
|
|
138
|
+
* What the reply's `values` hold.
|
|
139
|
+
*/
|
|
140
|
+
reply: string;
|
|
141
|
+
};
|
|
142
|
+
export type SurfaceCatalog = {
|
|
143
|
+
/**
|
|
144
|
+
* The format version, `surface/1`.
|
|
145
|
+
*/
|
|
146
|
+
version: string;
|
|
147
|
+
/**
|
|
148
|
+
* The intents.
|
|
149
|
+
*/
|
|
150
|
+
intents: Readonly<Partial<Record<SurfaceIntent, CatalogIntent>>>;
|
|
151
|
+
/**
|
|
152
|
+
* The node types.
|
|
153
|
+
*/
|
|
154
|
+
nodes: Readonly<Record<string, CatalogNode>>;
|
|
155
|
+
};
|
|
156
|
+
/**
|
|
157
|
+
* The full catalog. Frozen; narrow it with `narrowCatalog()`.
|
|
158
|
+
* @type {SurfaceCatalog}
|
|
159
|
+
*/
|
|
160
|
+
export declare const CATALOG: SurfaceCatalog;
|
|
161
|
+
/**
|
|
162
|
+
* Returns a catalog limited to some intents and node types. It can only narrow: a name the
|
|
163
|
+
* catalog does not have is refused, and so is an intent whose required node would be removed
|
|
164
|
+
* (`ask` without `fields`, `choose` without `choice`, `review` without `diff` or `table`,
|
|
165
|
+
* `questionnaire` without `questionnaire`). A node that belongs to one intent leaves with it.
|
|
166
|
+
* @param {SurfaceCatalog} catalog The catalog to narrow: `CATALOG` or an already narrowed one.
|
|
167
|
+
* @param {{intents?: SurfaceIntent[], nodes?: string[]}} [options] What to keep; all when left out.
|
|
168
|
+
* @returns {SurfaceCatalog} A new frozen catalog.
|
|
169
|
+
* @throws {TypeError} For an unknown name, an intent left without its required node, or a
|
|
170
|
+
* catalog that is not the library's.
|
|
171
|
+
*/
|
|
172
|
+
export declare function narrowCatalog(catalog: SurfaceCatalog, options?: {
|
|
173
|
+
intents?: SurfaceIntent[];
|
|
174
|
+
nodes?: string[];
|
|
175
|
+
}): SurfaceCatalog;
|
|
176
|
+
/**
|
|
177
|
+
* Throws unless the catalog is the library's, or narrowed from it: every intent and node entry
|
|
178
|
+
* must be the library's own frozen entry, so a catalog cannot be widened by building one by hand.
|
|
179
|
+
* @param {unknown} catalog
|
|
180
|
+
* @returns {asserts catalog is SurfaceCatalog}
|
|
181
|
+
* @throws {TypeError} When the catalog is not the library's.
|
|
182
|
+
*/
|
|
183
|
+
export declare function assertCatalog(catalog: unknown): asserts catalog is SurfaceCatalog;
|
|
184
|
+
export type Profile = 'full' | 'strict';
|
|
185
|
+
export type JsonSchema = Record<string, any>;
|
|
186
|
+
/**
|
|
187
|
+
* The JSON Schema (2020-12) of the format for a catalog: one operation line, and a whole document.
|
|
188
|
+
* Validation, not the schema, is what decides: the schema cannot see duplicate ids, the order of
|
|
189
|
+
* inputs a condition may name, or the application's entities, and it leaves out the repairs the
|
|
190
|
+
* validator makes.
|
|
191
|
+
* @param {SurfaceCatalog} [catalog=CATALOG]
|
|
192
|
+
* @returns {{line: JsonSchema, document: JsonSchema}}
|
|
193
|
+
*/
|
|
194
|
+
export declare function surfaceSchema(catalog?: SurfaceCatalog): {
|
|
195
|
+
line: JsonSchema;
|
|
196
|
+
document: JsonSchema;
|
|
197
|
+
};
|
|
198
|
+
export type SurfaceTool = {
|
|
199
|
+
/**
|
|
200
|
+
* The tool's name.
|
|
201
|
+
*/
|
|
202
|
+
name: string;
|
|
203
|
+
/**
|
|
204
|
+
* What it does, for the model.
|
|
205
|
+
*/
|
|
206
|
+
description: string;
|
|
207
|
+
/**
|
|
208
|
+
* The arguments' JSON Schema, usable with strict structured
|
|
209
|
+
* output.
|
|
210
|
+
*/
|
|
211
|
+
parameters: JsonSchema;
|
|
212
|
+
};
|
|
213
|
+
/**
|
|
214
|
+
* A function-calling tool definition in the neutral shape providers adapt.
|
|
215
|
+
* @typedef {Object} SurfaceTool
|
|
216
|
+
* @property {string} name The tool's name.
|
|
217
|
+
* @property {string} description What it does, for the model.
|
|
218
|
+
* @property {JsonSchema} parameters The arguments' JSON Schema, usable with strict structured
|
|
219
|
+
* output.
|
|
220
|
+
*/
|
|
221
|
+
/**
|
|
222
|
+
* The tool definitions a model calls to put a surface in front of the person: `show_surface`
|
|
223
|
+
* (any intent, a whole document) and `ask_user` (an `ask` surface; left out when the catalog has
|
|
224
|
+
* no `ask`). The person's reply is each call's result. Arguments follow the strict profile: every
|
|
225
|
+
* key present, `null` for one that does not apply, schema properties and table rows as lists.
|
|
226
|
+
* @param {SurfaceCatalog} [catalog=CATALOG]
|
|
227
|
+
* @returns {SurfaceTool[]}
|
|
228
|
+
*/
|
|
229
|
+
export declare function surfaceTools(catalog?: SurfaceCatalog): SurfaceTool[];
|
|
230
|
+
export type WorkedExample = {
|
|
231
|
+
title: string;
|
|
232
|
+
intro: string;
|
|
233
|
+
intent: SurfaceIntent;
|
|
234
|
+
nodes: string[];
|
|
235
|
+
document: Record<string, any>;
|
|
236
|
+
lines: Record<string, any>[];
|
|
237
|
+
before: string;
|
|
238
|
+
after: string;
|
|
239
|
+
};
|
|
240
|
+
/**
|
|
241
|
+
* The worked examples that fit a catalog: at most `count`, in order of preference.
|
|
242
|
+
* @param {SurfaceCatalog} catalog @param {number} [count=2]
|
|
243
|
+
* @returns {WorkedExample[]}
|
|
244
|
+
*/
|
|
245
|
+
export declare function workedExamples(catalog?: SurfaceCatalog, count?: number): WorkedExample[];
|
|
246
|
+
/**
|
|
247
|
+
* The model-facing guide to composing surfaces for a catalog, as one Markdown string: the
|
|
248
|
+
* delivery, the intents, a node reference generated from the catalog, the rules, and two worked
|
|
249
|
+
* examples written for the delivery `mode` picks. `rules` are the application's own lines,
|
|
250
|
+
* appended after the library's. The guide only informs; validation and the application's policy
|
|
251
|
+
* enforce.
|
|
252
|
+
* @param {SurfaceCatalog} [catalog=CATALOG]
|
|
253
|
+
* @param {{mode?: 'tool'|'inline', rules?: string[]}} [options]
|
|
254
|
+
* @returns {string}
|
|
255
|
+
* @throws {TypeError} For an unknown mode or a catalog that is not the library's.
|
|
256
|
+
*/
|
|
257
|
+
export declare function surfacePrompt(catalog?: SurfaceCatalog, options?: {
|
|
258
|
+
mode?: 'tool' | 'inline';
|
|
259
|
+
rules?: string[];
|
|
260
|
+
}): string;
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
export type InputSchema = import('./schema.js').InputSchema;
|
|
2
|
+
export type OpenSurfaceOptions = import('./surface.js').OpenSurfaceOptions;
|
|
3
|
+
export type ElicitRequest = {
|
|
4
|
+
/**
|
|
5
|
+
* What is asked, and why.
|
|
6
|
+
*/
|
|
7
|
+
message: string;
|
|
8
|
+
/**
|
|
9
|
+
* One flat object of `string`, `number`, `integer`,
|
|
10
|
+
* `boolean` and multiple-choice properties.
|
|
11
|
+
*/
|
|
12
|
+
requestedSchema: InputSchema;
|
|
13
|
+
};
|
|
14
|
+
export type ElicitResult = {
|
|
15
|
+
/**
|
|
16
|
+
* `accept` with the content, `decline` when the
|
|
17
|
+
* person refused, `cancel` when they closed the form.
|
|
18
|
+
*/
|
|
19
|
+
action: 'accept' | 'decline' | 'cancel';
|
|
20
|
+
/**
|
|
21
|
+
* The submitted values,
|
|
22
|
+
* checked against the schema; only with `accept`.
|
|
23
|
+
*/
|
|
24
|
+
content?: Record<string, string | number | boolean | string[]>;
|
|
25
|
+
};
|
|
26
|
+
export type ElicitOptions = Omit<OpenSurfaceOptions, 'document'> & {
|
|
27
|
+
title?: string;
|
|
28
|
+
author?: string;
|
|
29
|
+
lang?: string;
|
|
30
|
+
msg?: Record<string, string> | Record<string, Record<string, string>>;
|
|
31
|
+
};
|
|
32
|
+
/** @typedef {import('./schema.js').InputSchema} InputSchema */
|
|
33
|
+
/** @typedef {import('./surface.js').OpenSurfaceOptions} OpenSurfaceOptions */
|
|
34
|
+
/**
|
|
35
|
+
* A form-mode elicitation request.
|
|
36
|
+
* @typedef {Object} ElicitRequest
|
|
37
|
+
* @property {string} message What is asked, and why.
|
|
38
|
+
* @property {InputSchema} requestedSchema One flat object of `string`, `number`, `integer`,
|
|
39
|
+
* `boolean` and multiple-choice properties.
|
|
40
|
+
*/
|
|
41
|
+
/**
|
|
42
|
+
* The person's answer.
|
|
43
|
+
* @typedef {Object} ElicitResult
|
|
44
|
+
* @property {'accept'|'decline'|'cancel'} action `accept` with the content, `decline` when the
|
|
45
|
+
* person refused, `cancel` when they closed the form.
|
|
46
|
+
* @property {Record<string, string|number|boolean|string[]>} [content] The submitted values,
|
|
47
|
+
* checked against the schema; only with `accept`.
|
|
48
|
+
*/
|
|
49
|
+
/**
|
|
50
|
+
* Options of `elicit()`: where the form goes, who asks, and the Surface's own options.
|
|
51
|
+
* @typedef {Omit<OpenSurfaceOptions, 'document'> & {
|
|
52
|
+
* title?: string,
|
|
53
|
+
* author?: string,
|
|
54
|
+
* lang?: string,
|
|
55
|
+
* msg?: Record<string, string>|Record<string, Record<string, string>>
|
|
56
|
+
* }} ElicitOptions
|
|
57
|
+
*/
|
|
58
|
+
/**
|
|
59
|
+
* The `ask` surface `elicit()` draws for a request: the server's message as plain text — its
|
|
60
|
+
* characters drawn as given, never read as markup — and the form, with Submit and Decline. Labels
|
|
61
|
+
* resolve as a Surface's own do: `options.msg` for the active language, then its flat entries, the
|
|
62
|
+
* host translator, and English. Pure: it draws nothing.
|
|
63
|
+
* @param {ElicitRequest} request
|
|
64
|
+
* @param {ElicitOptions} [options] `title`, `author`, `msg` and `lang` are read.
|
|
65
|
+
* @returns {import('./validate.js').SurfaceDocument}
|
|
66
|
+
* @throws {TypeError} When the schema lies outside the subset, naming what is unsupported.
|
|
67
|
+
*/
|
|
68
|
+
export declare function elicitDocument(request: ElicitRequest, options?: ElicitOptions): import('./validate.js').SurfaceDocument;
|
|
69
|
+
/**
|
|
70
|
+
* Asks the person for the values a request names, in a Dialog — or inline in `options.target` —
|
|
71
|
+
* and resolves with their answer: Submit resolves `accept` with the values checked against the
|
|
72
|
+
* schema, Decline resolves `decline`, and Escape or closing resolves `cancel`. The surface is
|
|
73
|
+
* `elicitDocument()`'s. `options.signal` withdraws the request: when it aborts — or if it already
|
|
74
|
+
* has — the form is cancelled (a dialog closes, an inline form stays as its receipt) and the
|
|
75
|
+
* promise resolves `cancel`.
|
|
76
|
+
* @param {ElicitRequest} request
|
|
77
|
+
* @param {ElicitOptions} [options]
|
|
78
|
+
* @returns {Promise<ElicitResult>}
|
|
79
|
+
* @throws {TypeError} Rejects when the schema lies outside the subset, naming what is unsupported.
|
|
80
|
+
*/
|
|
81
|
+
export declare function elicit(request: ElicitRequest, options?: ElicitOptions): Promise<ElicitResult>;
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
export type ElicitResult = import('./elicit.js').ElicitResult;
|
|
2
|
+
export type InputSchema = import('./schema.js').InputSchema;
|
|
3
|
+
export type SurfaceReply = import('./surface.js').SurfaceReply;
|
|
4
|
+
/** @typedef {import('./elicit.js').ElicitResult} ElicitResult */
|
|
5
|
+
/** @typedef {import('./schema.js').InputSchema} InputSchema */
|
|
6
|
+
/** @typedef {import('./surface.js').SurfaceReply} SurfaceReply */
|
|
7
|
+
/** The MCP revision whose elicitation the handler implements. */
|
|
8
|
+
export declare const MCP_ELICITATION_VERSION = "2026-07-28";
|
|
9
|
+
export type ElicitationParams = {
|
|
10
|
+
/**
|
|
11
|
+
* How the server asks.
|
|
12
|
+
*/
|
|
13
|
+
mode?: 'form' | 'url';
|
|
14
|
+
/**
|
|
15
|
+
* What is asked, and why.
|
|
16
|
+
*/
|
|
17
|
+
message: string;
|
|
18
|
+
/**
|
|
19
|
+
* Form mode: one flat object of primitive and
|
|
20
|
+
* multiple-choice properties.
|
|
21
|
+
*/
|
|
22
|
+
requestedSchema?: InputSchema;
|
|
23
|
+
/**
|
|
24
|
+
* URL mode: the page the person is sent to, `https:` only.
|
|
25
|
+
*/
|
|
26
|
+
url?: string;
|
|
27
|
+
/**
|
|
28
|
+
* Sent by servers of the 2025-11-25 revision; ignored.
|
|
29
|
+
*/
|
|
30
|
+
elicitationId?: string;
|
|
31
|
+
};
|
|
32
|
+
export type ElicitationHandlerOptions = {
|
|
33
|
+
/**
|
|
34
|
+
* The name of the server that asks, as the client knows it; shown as
|
|
35
|
+
* "Asked by <server>". Required: the person must always see who asks.
|
|
36
|
+
*/
|
|
37
|
+
serverName: string;
|
|
38
|
+
/**
|
|
39
|
+
* Display names by key; when it lists
|
|
40
|
+
* `serverName`, that entry's name is shown instead.
|
|
41
|
+
*/
|
|
42
|
+
authors?: Record<string, {
|
|
43
|
+
name: string;
|
|
44
|
+
}>;
|
|
45
|
+
/**
|
|
46
|
+
* Where the surface goes inline; a Dialog without one.
|
|
47
|
+
*/
|
|
48
|
+
target?: Element | string | null;
|
|
49
|
+
/**
|
|
50
|
+
* Opens the page in URL mode, after the person
|
|
51
|
+
* agreed. It receives the normalised address and must open it in a new browsing context that
|
|
52
|
+
* cannot reach the application; returning `false` or throwing means it was not opened, and the
|
|
53
|
+
* request answers `cancel`. The default opens a new tab with `noopener` and `noreferrer`.
|
|
54
|
+
*/
|
|
55
|
+
open?: (url: string) => boolean | void;
|
|
56
|
+
/**
|
|
57
|
+
* Localized
|
|
58
|
+
* messages, flat or by language: the `mcp.*` keys, and the `surface.*` keys of the form.
|
|
59
|
+
*/
|
|
60
|
+
msg?: Record<string, string> | Record<string, Record<string, string>>;
|
|
61
|
+
};
|
|
62
|
+
export type ElicitationContext = {
|
|
63
|
+
/**
|
|
64
|
+
* Withdraws the request — the server cancelled it, the call
|
|
65
|
+
* timed out, the session closed: the surface is cancelled with the reason `stopped` (a dialog
|
|
66
|
+
* closes, an inline surface stays as its receipt), nothing opens, and the request resolves
|
|
67
|
+
* `cancel`. Already aborted, it resolves `cancel` without drawing anything. Abort it as well
|
|
68
|
+
* when the application removes an inline `target`, or the request stays pending.
|
|
69
|
+
*/
|
|
70
|
+
signal?: AbortSignal | null;
|
|
71
|
+
};
|
|
72
|
+
export type ElicitationUrl = {
|
|
73
|
+
/**
|
|
74
|
+
* The normalised address: what is shown in full and what is opened.
|
|
75
|
+
*/
|
|
76
|
+
href: string;
|
|
77
|
+
/**
|
|
78
|
+
* The host, with its port when it has one, as the browser will reach it.
|
|
79
|
+
*/
|
|
80
|
+
host: string;
|
|
81
|
+
/**
|
|
82
|
+
* Whether the host holds an internationalised (Punycode) label,
|
|
83
|
+
* which can imitate another name.
|
|
84
|
+
*/
|
|
85
|
+
international: boolean;
|
|
86
|
+
};
|
|
87
|
+
/**
|
|
88
|
+
* An elicitation request's `params`. Form mode is the default when `mode` is absent; fields a mode
|
|
89
|
+
* does not use, such as the `elicitationId` of earlier revisions, are ignored.
|
|
90
|
+
* @typedef {Object} ElicitationParams
|
|
91
|
+
* @property {'form'|'url'} [mode] How the server asks.
|
|
92
|
+
* @property {string} message What is asked, and why.
|
|
93
|
+
* @property {InputSchema} [requestedSchema] Form mode: one flat object of primitive and
|
|
94
|
+
* multiple-choice properties.
|
|
95
|
+
* @property {string} [url] URL mode: the page the person is sent to, `https:` only.
|
|
96
|
+
* @property {string} [elicitationId] Sent by servers of the 2025-11-25 revision; ignored.
|
|
97
|
+
*/
|
|
98
|
+
/**
|
|
99
|
+
* Options of `elicitationHandler()`.
|
|
100
|
+
* @typedef {Object} ElicitationHandlerOptions
|
|
101
|
+
* @property {string} serverName The name of the server that asks, as the client knows it; shown as
|
|
102
|
+
* "Asked by <server>". Required: the person must always see who asks.
|
|
103
|
+
* @property {Record<string, {name: string}>} [authors={}] Display names by key; when it lists
|
|
104
|
+
* `serverName`, that entry's name is shown instead.
|
|
105
|
+
* @property {Element|string|null} [target=null] Where the surface goes inline; a Dialog without one.
|
|
106
|
+
* @property {(url: string) => boolean|void} [open] Opens the page in URL mode, after the person
|
|
107
|
+
* agreed. It receives the normalised address and must open it in a new browsing context that
|
|
108
|
+
* cannot reach the application; returning `false` or throwing means it was not opened, and the
|
|
109
|
+
* request answers `cancel`. The default opens a new tab with `noopener` and `noreferrer`.
|
|
110
|
+
* @property {Record<string, string>|Record<string, Record<string, string>>} [msg] Localized
|
|
111
|
+
* messages, flat or by language: the `mcp.*` keys, and the `surface.*` keys of the form.
|
|
112
|
+
*/
|
|
113
|
+
/**
|
|
114
|
+
* What the client knows about one request beyond its `params`.
|
|
115
|
+
* @typedef {Object} ElicitationContext
|
|
116
|
+
* @property {AbortSignal|null} [signal] Withdraws the request — the server cancelled it, the call
|
|
117
|
+
* timed out, the session closed: the surface is cancelled with the reason `stopped` (a dialog
|
|
118
|
+
* closes, an inline surface stays as its receipt), nothing opens, and the request resolves
|
|
119
|
+
* `cancel`. Already aborted, it resolves `cancel` without drawing anything. Abort it as well
|
|
120
|
+
* when the application removes an inline `target`, or the request stays pending.
|
|
121
|
+
*/
|
|
122
|
+
/**
|
|
123
|
+
* A URL-mode address, checked and normalised.
|
|
124
|
+
* @typedef {Object} ElicitationUrl
|
|
125
|
+
* @property {string} href The normalised address: what is shown in full and what is opened.
|
|
126
|
+
* @property {string} host The host, with its port when it has one, as the browser will reach it.
|
|
127
|
+
* @property {boolean} international Whether the host holds an internationalised (Punycode) label,
|
|
128
|
+
* which can imitate another name.
|
|
129
|
+
*/
|
|
130
|
+
/**
|
|
131
|
+
* Creates the function an MCP client installs to answer elicitation requests. Form mode draws an
|
|
132
|
+
* `ask` surface through `elicit()`. URL mode draws a `confirm` surface naming the page's host,
|
|
133
|
+
* emphasised, and its full address; nothing is loaded and nothing opens until the person agrees.
|
|
134
|
+
* Open the page opens it in a new browsing context, without opener or referrer, and answers
|
|
135
|
+
* `accept`; Decline answers `decline`; Cancel, Escape or closing the dialog answers `cancel`.
|
|
136
|
+
* @param {ElicitationHandlerOptions} options
|
|
137
|
+
* @returns {(params: ElicitationParams, context?: ElicitationContext) => Promise<ElicitResult>}
|
|
138
|
+
* Resolves the result to send back;
|
|
139
|
+
* rejects with a `TypeError` — so the client can answer the server with an error — for a request
|
|
140
|
+
* that is not an object, an unknown `mode`, a `message` that is not text, a schema outside the
|
|
141
|
+
* supported subset, or an address that is not a valid `https:` URL.
|
|
142
|
+
* @throws {TypeError} When `serverName` is missing.
|
|
143
|
+
*/
|
|
144
|
+
export declare function elicitationHandler(options: ElicitationHandlerOptions): (params: ElicitationParams, context?: ElicitationContext) => Promise<ElicitResult>;
|
|
145
|
+
/**
|
|
146
|
+
* Checks a URL-mode address the way surface links are checked, and normalises it: an absolute
|
|
147
|
+
* `https://` address in lower case, without credentials, spaces, backslashes, control or invisible
|
|
148
|
+
* formatting characters, at most 2000 characters. The address returned is the parsed one, so the
|
|
149
|
+
* host shown and the page opened come from the same string.
|
|
150
|
+
* @param {unknown} value The request's `url`.
|
|
151
|
+
* @returns {ElicitationUrl}
|
|
152
|
+
* @throws {TypeError} When the address is missing or refused.
|
|
153
|
+
*/
|
|
154
|
+
export declare function elicitationUrl(value: unknown): ElicitationUrl;
|
|
155
|
+
/**
|
|
156
|
+
* The `confirm` surface that asks before a URL-mode page opens: the server's message as plain
|
|
157
|
+
* text, the host emphasised, the full address, a warning for an internationalised host, and what
|
|
158
|
+
* opening does. No part of it is a link.
|
|
159
|
+
* @param {string} message The server's message.
|
|
160
|
+
* @param {ElicitationUrl} url From `elicitationUrl()`.
|
|
161
|
+
* @param {(key: string, ...args: unknown[]) => string} [text] Resolves the `mcp.*` messages;
|
|
162
|
+
* English by default.
|
|
163
|
+
* @returns {import('./validate.js').SurfaceDocument}
|
|
164
|
+
*/
|
|
165
|
+
export declare function urlConsentDocument(message: string, url: ElicitationUrl, text?: (key: string, ...args: unknown[]) => string): import('./validate.js').SurfaceDocument;
|