@sisense/sdk-ai-core 0.17.0 → 0.60.1
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/dist/__vite-browser-external-l0sNRNKZ.js +1 -0
- package/dist/constants.d.ts +35 -0
- package/dist/engines/atomic-handle-args.d.ts +45 -0
- package/dist/engines/atomic-tool-requirements.d.ts +38 -0
- package/dist/engines/author-pulse/actions/create.d.ts +9 -0
- package/dist/engines/author-pulse/actions/define.d.ts +9 -0
- package/dist/engines/author-pulse/actions/load-existing.d.ts +9 -0
- package/dist/engines/author-pulse/actions/redefine.d.ts +9 -0
- package/dist/engines/author-pulse/actions/set-receive-notifications.d.ts +8 -0
- package/dist/engines/author-pulse/actions/update-spec.d.ts +11 -0
- package/dist/engines/author-pulse/actions/update-workflow.d.ts +9 -0
- package/dist/engines/author-pulse/atomic-adapter.d.ts +10 -0
- package/dist/engines/author-pulse/atomic-tools.d.ts +362 -0
- package/dist/engines/author-pulse/author-pulse-engine.d.ts +21 -0
- package/dist/engines/author-pulse/index.d.ts +9 -0
- package/dist/engines/author-pulse/shared/adjustment-error.d.ts +15 -0
- package/dist/engines/author-pulse/shared/assemble-create-workflow-payload.d.ts +36 -0
- package/dist/engines/author-pulse/shared/assert-agentic-workflow.d.ts +12 -0
- package/dist/engines/author-pulse/shared/compile-query-from-prompt.d.ts +95 -0
- package/dist/engines/author-pulse/shared/decision-spec-validation.d.ts +84 -0
- package/dist/engines/author-pulse/shared/notification-urls.d.ts +52 -0
- package/dist/engines/author-pulse/shared/pulse-knowledge.d.ts +36 -0
- package/dist/engines/author-pulse/shared/pulse-signature.d.ts +39 -0
- package/dist/engines/author-pulse/shared/resolve-frequency.d.ts +18 -0
- package/dist/engines/author-pulse/shared/staging.d.ts +65 -0
- package/dist/engines/author-pulse/shared/workflow-ownership.d.ts +14 -0
- package/dist/engines/author-pulse/types.d.ts +1385 -0
- package/dist/engines/build-chart/atomic-adapter.d.ts +20 -0
- package/dist/engines/build-chart/atomic-tools.d.ts +214 -0
- package/dist/engines/build-chart/build-chart-engine.d.ts +1 -1
- package/dist/engines/build-chart/chart-tool-name.d.ts +3 -0
- package/dist/engines/build-chart/create-chart/assemble-chart-widget.d.ts +1 -1
- package/dist/engines/build-chart/create-chart/chart-json-axes-mapping.d.ts +1 -1
- package/dist/engines/build-chart/create-chart/create-chart.d.ts +1 -1
- package/dist/engines/build-chart/create-chart/derive-chart-title.d.ts +7 -0
- package/dist/engines/build-chart/create-chart/generate-chart-recommendations.d.ts +2 -2
- package/dist/engines/build-chart/create-chart/resolve-chart-query.d.ts +4 -0
- package/dist/engines/build-chart/shared/normalize-cartesian-axes-mapping.d.ts +1 -1
- package/dist/engines/build-chart/shared/sync-chart-state-measure-flags.d.ts +3 -0
- package/dist/engines/build-chart/types.d.ts +38 -19
- package/dist/engines/build-chart/update-chart/apply-prior-chart-style.d.ts +8 -5
- package/dist/engines/build-chart/update-chart/chart-options-schemas.d.ts +18 -18
- package/dist/engines/build-chart/update-chart/schemas.d.ts +2 -2
- package/dist/engines/build-chart/update-chart/update-chart-data-options.d.ts +7 -2
- package/dist/engines/build-chart/update-chart/update-chart-query.d.ts +1 -1
- package/dist/engines/build-chart/update-chart/update-chart-style-options.d.ts +7 -2
- package/dist/engines/build-chart/update-chart/update-chart-title.d.ts +1 -1
- package/dist/engines/build-chart/update-chart/update-chart-type.d.ts +7 -2
- package/dist/engines/build-csv-model/build-csv-model-engine.d.ts +1 -1
- package/dist/engines/build-csv-model/types.d.ts +1 -1
- package/dist/engines/build-dashboard/add-dashboard-narration.d.ts +50 -0
- package/dist/engines/build-dashboard/add-dashboard-widgets.d.ts +1 -1
- package/dist/engines/build-dashboard/atomic-adapter.d.ts +21 -0
- package/dist/engines/build-dashboard/atomic-tools.d.ts +231 -0
- package/dist/engines/build-dashboard/build-dashboard-engine.d.ts +1 -1
- package/dist/engines/build-dashboard/build-dashboard-service.d.ts +2 -1
- package/dist/engines/build-dashboard/create-dashboard.d.ts +3 -4
- package/dist/engines/build-dashboard/dashboard-filters/manipulate-dashboard-filters.d.ts +2 -1
- package/dist/engines/build-dashboard/dashboard-filters/translate-filters.d.ts +17 -1
- package/dist/engines/build-dashboard/index.d.ts +2 -0
- package/dist/engines/build-dashboard/layout/place-widget.d.ts +53 -0
- package/dist/engines/build-dashboard/load-existing-fusion-dashboard.d.ts +1 -1
- package/dist/engines/build-dashboard/remove-dashboard-widgets.d.ts +4 -0
- package/dist/engines/build-dashboard/resolve-chart-widgets.d.ts +16 -0
- package/dist/engines/build-dashboard/types.d.ts +180 -18
- package/dist/engines/build-data-model/build-data-model-engine.d.ts +1 -1
- package/dist/engines/build-data-model/types.d.ts +1 -1
- package/dist/engines/build-query/build-query-engine.d.ts +33 -5
- package/dist/engines/build-query/index.d.ts +1 -1
- package/dist/engines/build-query/types.d.ts +216 -3
- package/dist/engines/build-status/build-status-engine.d.ts +8 -0
- package/dist/engines/build-status/builds-client.d.ts +44 -0
- package/dist/engines/build-status/index.d.ts +2 -0
- package/dist/engines/build-status/types.d.ts +177 -0
- package/dist/engines/datamodel-graph/data-model-map-text.d.ts +28 -0
- package/dist/engines/datamodel-graph/datamodel-graph-engine.d.ts +31 -0
- package/dist/engines/datamodel-graph/index.d.ts +4 -0
- package/dist/engines/datamodel-graph/summaries.d.ts +97 -0
- package/dist/engines/datamodel-graph/test-fixtures.d.ts +42 -0
- package/dist/engines/datamodel-graph/types.d.ts +190 -0
- package/dist/engines/evaluate-pulse/evaluate-pulse-engine.d.ts +10 -0
- package/dist/engines/evaluate-pulse/index.d.ts +2 -0
- package/dist/engines/evaluate-pulse/types.d.ts +85 -0
- package/dist/engines/get-dashboard-narration/get-dashboard-narration-engine.d.ts +23 -0
- package/dist/engines/get-dashboard-narration/index.d.ts +2 -0
- package/dist/engines/get-dashboard-narration/types.d.ts +64 -0
- package/dist/engines/get-dashboards/get-dashboards-engine.d.ts +1 -1
- package/dist/engines/get-dashboards/types.d.ts +16 -4
- package/dist/engines/get-data-preview/get-data-preview-engine.d.ts +18 -0
- package/dist/engines/get-data-preview/index.d.ts +2 -0
- package/dist/engines/get-data-preview/types.d.ts +35 -0
- package/dist/engines/get-data-source-fields/get-data-source-fields-engine.d.ts +12 -6
- package/dist/engines/get-data-source-fields/index.d.ts +1 -0
- package/dist/engines/get-data-source-fields/model-relations.d.ts +38 -0
- package/dist/engines/get-data-source-fields/types.d.ts +49 -3
- package/dist/engines/get-data-sources/get-data-sources-engine.d.ts +1 -1
- package/dist/engines/get-data-sources/types.d.ts +2 -2
- package/dist/engines/index.d.ts +17 -0
- package/dist/engines/inspect-pulse/atomic-adapter.d.ts +8 -0
- package/dist/engines/inspect-pulse/atomic-tools.d.ts +60 -0
- package/dist/engines/inspect-pulse/index.d.ts +4 -0
- package/dist/engines/inspect-pulse/inspect-pulse-engine.d.ts +7 -0
- package/dist/engines/inspect-pulse/types.d.ts +209 -0
- package/dist/engines/manage-perspectives/manage-perspectives-engine.d.ts +5 -1
- package/dist/engines/manage-perspectives/types.d.ts +13 -8
- package/dist/engines/pulse-tool-words.d.ts +62 -0
- package/dist/engines/recommend-queries/recommend-queries-engine.d.ts +1 -1
- package/dist/engines/recommend-queries/types.d.ts +1 -1
- package/dist/engines/shared/existing-answer-cascade.d.ts +52 -0
- package/dist/engines/shared/get-filters-json-for-llm-summary.d.ts +2 -2
- package/dist/engines/shared/nlq-query-helpers.d.ts +2 -2
- package/dist/engines/shared/project-dashboard-json.d.ts +151 -0
- package/dist/engines/shared/project-widget-json.d.ts +67 -0
- package/dist/engines/shared/projection-helpers.d.ts +19 -0
- package/dist/engines/shared/redact-data-models-closed-to-ai.d.ts +55 -0
- package/dist/engines/shared/redact-hidden-columns-from-ai.d.ts +55 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +57916 -30543
- package/dist/services/ai-access/ai-access-service.d.ts +68 -0
- package/dist/services/dashboards/dashboards-service.d.ts +9 -3
- package/dist/services/dashboards/fusion-dashboards-service.d.ts +34 -4
- package/dist/services/data-sources/data-sources-service.d.ts +131 -2
- package/dist/services/data-sources/find-data-source-by-title.d.ts +8 -0
- package/dist/services/datamodel-graph/datamodel-graph-service.d.ts +457 -0
- package/dist/services/existing-answer/existing-answer-query-service.d.ts +31 -0
- package/dist/services/formulas/formulas-service.d.ts +19 -0
- package/dist/services/hide-from-ai/hide-from-ai.d.ts +31 -0
- package/dist/services/knowledge-graph/knowledge-graph-service.d.ts +96 -0
- package/dist/services/llm/llm-consumption-service.d.ts +7 -2
- package/dist/services/llm/llm-settings-service.d.ts +49 -5
- package/dist/services/nlq/nlq-preview-dataset.d.ts +34 -0
- package/dist/services/nlq/nlq-service.d.ts +138 -3
- package/dist/services/pulse/evaluate-pulse-client.d.ts +78 -0
- package/dist/services/pulse/pulse-alerts-service.d.ts +264 -0
- package/dist/services/pulse/pulse-events-service.d.ts +217 -0
- package/dist/services/semantic-search/semantic-search-service.d.ts +43 -0
- package/dist/services/tool-store/tool-store-service.d.ts +32 -0
- package/dist/services/users-groups-service.d.ts +37 -0
- package/dist/skills/index.d.ts +127 -0
- package/dist/tool-availability/controlled-tools.d.ts +56 -0
- package/dist/tool-availability/index.d.ts +4 -0
- package/dist/tool-availability/offer-tools.d.ts +44 -0
- package/dist/tool-availability/resolve-tool-availability.d.ts +68 -0
- package/dist/tool-availability/withdrawn-text.d.ts +33 -0
- package/dist/tool-catalog/catalog.d.ts +387 -0
- package/dist/tool-catalog/index.d.ts +3 -0
- package/dist/tool-catalog/manifest.d.ts +5 -0
- package/dist/tool-catalog/prototype-lookup.d.ts +10 -0
- package/dist/tool-catalog/types.d.ts +67 -0
- package/dist/tools.manifest.json +826 -0
- package/dist/utils/chat-stream-errors.d.ts +42 -0
- package/dist/utils/create-custom-fetch.d.ts +19 -1
- package/dist/utils/create-stream-completion.d.ts +84 -6
- package/dist/utils/create-structured-completion.d.ts +29 -2
- package/dist/utils/create-tools-completion.d.ts +9 -0
- package/dist/utils/deferred-tools.d.ts +45 -0
- package/dist/utils/dev-debug.d.ts +5 -0
- package/dist/utils/generate-suggestions.d.ts +32 -0
- package/dist/utils/http-client.d.ts +3 -1
- package/dist/utils/llm-call-observer.d.ts +83 -0
- package/dist/utils/llm-client.d.ts +11 -1
- package/dist/utils/quoted-text.d.ts +6 -0
- package/dist/utils/server-error-body.d.ts +23 -0
- package/dist/utils/text-tokens.d.ts +35 -0
- package/dist/utils/user-action-tracking.d.ts +48 -5
- package/dist/utils/zod-utils.d.ts +9 -1
- package/package.json +28 -19
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
import { HttpClient } from '@sisense/sdk-rest-client';
|
|
2
|
+
import { AgenticAlertContext, AgenticDiffSignal, PulseAlertAction, PulseAlertParty, PulseAlertScheduler, PulseAlertSource } from './pulse-alerts-service';
|
|
3
|
+
/** Every read in this file only ever calls `.get` — narrowed so callers/mocks don't need to satisfy the full `HttpClient` surface (post/patch/delete/auth/etc). */
|
|
4
|
+
export type PulseReadClient = Pick<HttpClient, 'get'>;
|
|
5
|
+
export type PulseAlertCondition = {
|
|
6
|
+
type: 'fixed' | 'smart';
|
|
7
|
+
operator?: string;
|
|
8
|
+
leftOperand?: unknown;
|
|
9
|
+
rightOperand?: unknown;
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* Pulse alert definition (the rule), as returned by `GET /api/v1/alerts`.
|
|
13
|
+
* Hand-rolled from vnext's response shape for that endpoint — no shared type
|
|
14
|
+
* package exists across vnext/sisense-client for this domain.
|
|
15
|
+
*/
|
|
16
|
+
export interface PulseAlertDto {
|
|
17
|
+
_id: string;
|
|
18
|
+
name: string;
|
|
19
|
+
message?: string;
|
|
20
|
+
enabled: boolean;
|
|
21
|
+
category: 'system' | 'kpi' | 'dashboard' | 'judgment';
|
|
22
|
+
type: 'build' | 'kpi' | 'upgradeVersion' | 'agentic';
|
|
23
|
+
/** Top-level sibling of `context`, matching vnext's shared `addAlert` schema. Only meaningful for a live-scheduled alert — absent for a cube-triggered agentic alert, which evaluates on every build instead. */
|
|
24
|
+
scheduler?: PulseAlertScheduler;
|
|
25
|
+
/** The requesting user is auto-injected as owner server-side on create and cannot be removed from `parties` by a later PATCH (SNS-132805). */
|
|
26
|
+
owner?: string;
|
|
27
|
+
parties?: PulseAlertParty[];
|
|
28
|
+
/** Muted recipients — still a party, but notifications are suppressed for these ids. */
|
|
29
|
+
disabledUsers?: string[];
|
|
30
|
+
/** Computed per caller by `GET /api/v1/alerts` (list only): false when the caller is in `disabledUsers`. */
|
|
31
|
+
receiveNotifications?: boolean;
|
|
32
|
+
/**
|
|
33
|
+
* Computed by vnext on `GET /api/v1/alerts` and `GET /api/v1/alerts/{id}`, never stored (SNS-134940):
|
|
34
|
+
* ISO instant a live alert is next checked — interval: `lastExecutedTime` plus the period raised
|
|
35
|
+
* to the admin minimum; calendar: the next cron run that minimum lets through. Absent when the
|
|
36
|
+
* alert is off, not on a Live model, live alerting is off, or on a vnext that predates it.
|
|
37
|
+
*/
|
|
38
|
+
nextCheckTime?: string;
|
|
39
|
+
action?: PulseAlertAction;
|
|
40
|
+
context?: {
|
|
41
|
+
/** Only present for `fixed`/`smart` `type: 'kpi'` alerts. */
|
|
42
|
+
condition?: PulseAlertCondition;
|
|
43
|
+
/** Present on every alert type — needed to tell a live-scheduled agentic alert (has a check frequency) from a cube-triggered one (evaluates on every build, no frequency to change). */
|
|
44
|
+
sources?: PulseAlertSource[];
|
|
45
|
+
} & Partial<AgenticAlertContext>;
|
|
46
|
+
}
|
|
47
|
+
/** Real vnext status enum (2-state POC scope) — do not widen without confirming the endpoint supports it. */
|
|
48
|
+
export type PulseEventStatus = 'ACKNOWLEDGED' | 'RESOLVED';
|
|
49
|
+
export interface PulseEventStatusUpdatedBy {
|
|
50
|
+
type: 'user' | 'agent' | 'workflow';
|
|
51
|
+
id?: string;
|
|
52
|
+
name?: string;
|
|
53
|
+
}
|
|
54
|
+
export interface PulseEventComment {
|
|
55
|
+
_id: string;
|
|
56
|
+
createdAt: string;
|
|
57
|
+
author?: string;
|
|
58
|
+
bodyMarkdown: string;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Alert fields embedded when `getActiveEvents` requests `expand=alert`. vnext's `expand=alert`
|
|
62
|
+
* query param returns the full alert document (confirmed empirically) — `type`/`category`
|
|
63
|
+
* included, not just `name`/`message`. Declared here so `list-notifications` can filter by `type`
|
|
64
|
+
* client-side instead of silently dropping data the server already sends.
|
|
65
|
+
*/
|
|
66
|
+
export interface PulseEventAlertRef {
|
|
67
|
+
_id: string;
|
|
68
|
+
name: string;
|
|
69
|
+
message?: string;
|
|
70
|
+
type?: PulseAlertDto['type'];
|
|
71
|
+
category?: PulseAlertDto['category'];
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Pulse event (a fired alert instance), as returned by `GET /api/v1/events`.
|
|
75
|
+
* Hand-rolled from vnext's response shape for that endpoint.
|
|
76
|
+
*/
|
|
77
|
+
export interface PulseEventDto {
|
|
78
|
+
_id: string;
|
|
79
|
+
time: string;
|
|
80
|
+
/** Alert this event fired from — expanded to name/message when fetched via `getActiveEvents` (`expand=alert`); a bare `_id` string from other call sites. */
|
|
81
|
+
alert: string | PulseEventAlertRef;
|
|
82
|
+
by?: {
|
|
83
|
+
name?: string;
|
|
84
|
+
oid?: string;
|
|
85
|
+
type?: 'dashboard' | 'cube' | 'server';
|
|
86
|
+
};
|
|
87
|
+
/** Absent when the event hasn't been acknowledged/resolved yet. */
|
|
88
|
+
status?: PulseEventStatus;
|
|
89
|
+
statusUpdatedAt?: string;
|
|
90
|
+
statusUpdatedBy?: PulseEventStatusUpdatedBy;
|
|
91
|
+
comments?: PulseEventComment[];
|
|
92
|
+
/**
|
|
93
|
+
* The evaluation cycle (`AgenticEvalRecord.evalId`) that produced this event — non-optional
|
|
94
|
+
* server-side since 2026-08-12 for an `agentic` alert's event. Lets `inspectPulse` jump
|
|
95
|
+
* straight from "here's what fired" to the full cycle behind it (`list-evals`/`get-eval`)
|
|
96
|
+
* instead of correlating by timestamp.
|
|
97
|
+
*/
|
|
98
|
+
evalId?: string;
|
|
99
|
+
/** Same narrative recorded on the originating eval cycle (`AgenticEvalRecord.narrative`), duplicated here for convenience — `agentic` alerts only. */
|
|
100
|
+
narrative?: string;
|
|
101
|
+
/** Optional structured evidence attached at fire time — `agentic` alerts only. */
|
|
102
|
+
signals?: AgenticDiffSignal[];
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Get Pulse alert definitions. Filters to enabled alerts by default — pass `includeDisabled: true`
|
|
106
|
+
* to also return paused (`enabled: false`) ones, e.g. to resolve a paused alert's id so it can be
|
|
107
|
+
* resumed via `authorPulse`'s `update-workflow`. Every returned alert still carries its own
|
|
108
|
+
* `enabled` field regardless of this filter, so a caller can always tell paused from active.
|
|
109
|
+
*/
|
|
110
|
+
export declare function getActiveAlerts(httpClient?: PulseReadClient, searchByName?: string, includeDisabled?: boolean): Promise<PulseAlertDto[]>;
|
|
111
|
+
/**
|
|
112
|
+
* Get one Pulse alert definition by id — the natural single-resource counterpart to the `PATCH`
|
|
113
|
+
* `pulse-alerts-service.ts#updateAlertCondition` already calls at the same path. Used by
|
|
114
|
+
* `inspectPulse`'s `get-workflow`, and internally by its other actions to confirm an alertId
|
|
115
|
+
* resolves to an `agentic` alert before reading further.
|
|
116
|
+
*/
|
|
117
|
+
export declare function getAlertById(alertId: string, httpClient?: PulseReadClient): Promise<PulseAlertDto>;
|
|
118
|
+
/**
|
|
119
|
+
* Get recent Pulse events (fired alert instances), optionally scoped to one alert.
|
|
120
|
+
*/
|
|
121
|
+
export declare function getActiveEvents(httpClient?: PulseReadClient, alertId?: string): Promise<PulseEventDto[]>;
|
|
122
|
+
/**
|
|
123
|
+
* One query's full outcome within a recorded evaluation cycle, as embedded in
|
|
124
|
+
* `AgenticEvalRecord.queries[]` — mirrors vnext's `agenticEvalQuery` shape exactly, including the
|
|
125
|
+
* raw `result.rows` a query returned that cycle (NOT a lightweight summary — vnext has no
|
|
126
|
+
* per-query summary shape on this endpoint). `outputs` is the same opaque transform-outputs bag
|
|
127
|
+
* `AgenticEvalResultRecord.outputs` carries (e.g. `outputs.diff = {hasPriorData, signals}`) —
|
|
128
|
+
* keyed by the query's declared transform types.
|
|
129
|
+
*/
|
|
130
|
+
export interface AgenticEvalQueryRecord {
|
|
131
|
+
name: string;
|
|
132
|
+
result?: {
|
|
133
|
+
columns?: Array<{
|
|
134
|
+
name: string;
|
|
135
|
+
role?: 'key' | 'value';
|
|
136
|
+
datatype?: string;
|
|
137
|
+
}>;
|
|
138
|
+
rows?: unknown[];
|
|
139
|
+
};
|
|
140
|
+
outputs?: Record<string, unknown>;
|
|
141
|
+
/** Set when the persisted row set for this query was capped server-side — a truncated row set is not a usable diff baseline either (mirrors `AgenticEvalResultRecord`'s own `truncated`, if vnext adds it there too). */
|
|
142
|
+
truncated?: boolean;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* One recorded evaluation cycle for an agentic alert, as returned by
|
|
146
|
+
* `GET /api/v1/alerts/{id}/agentic/evals` — the cycle-level decision/verdict + narrative (audit
|
|
147
|
+
* trail), distinct from the per-query raw result/diff data returned by
|
|
148
|
+
* `GET .../evals/{evalId}/results` (see `AgenticEvalResultRecord` below, which this record's own
|
|
149
|
+
* `queries[]` already duplicates in full — see `inspectPulseEngine`'s `list-evals`/`get-eval`,
|
|
150
|
+
* which strip `queries[].result.rows` before returning to the model for exactly that reason).
|
|
151
|
+
* Hand-rolled from vnext's `agenticEvalRecord` response schema.
|
|
152
|
+
*/
|
|
153
|
+
export interface AgenticEvalRecord {
|
|
154
|
+
evalId: string;
|
|
155
|
+
/** `'reasoning'` on records of a legacy alert, including the error records it still writes. */
|
|
156
|
+
evalMode: 'conditional' | 'reasoning';
|
|
157
|
+
/** What caused this cycle to run. Absent on records written before this field existed. */
|
|
158
|
+
trigger?: 'build' | 'schedule' | 'onDemand' | 'create';
|
|
159
|
+
fired: boolean;
|
|
160
|
+
narrative?: string;
|
|
161
|
+
eventId?: string;
|
|
162
|
+
/**
|
|
163
|
+
* Absent on an errored (`status: 'error'`) cycle — an error is not an evaluation outcome.
|
|
164
|
+
* `'inconclusive'` appears only on records written before SNS-134435.
|
|
165
|
+
*/
|
|
166
|
+
outcome?: 'met' | 'notMet' | 'noData' | 'inconclusive';
|
|
167
|
+
queries: AgenticEvalQueryRecord[];
|
|
168
|
+
crossQueryOutputs?: Record<string, unknown>;
|
|
169
|
+
status: 'ok' | 'error';
|
|
170
|
+
errorMessage?: string;
|
|
171
|
+
stepCount: number;
|
|
172
|
+
durationMs: number;
|
|
173
|
+
timestamp: string;
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* Up to `limit` most recent evaluation cycles (fired or not, error or not) for one agentic alert,
|
|
177
|
+
* newest first — the audit-trail read for "did this fire on the last build?" / "why did it fire
|
|
178
|
+
* last time?" without triggering a brand-new evaluation. Distinct from `evaluatePulse`
|
|
179
|
+
* (which runs a NEW check and writes a new record): this only reads what already happened.
|
|
180
|
+
*/
|
|
181
|
+
export declare function getAlertEvalHistory(alertId: string, limit?: number, httpClient?: PulseReadClient): Promise<AgenticEvalRecord[]>;
|
|
182
|
+
/**
|
|
183
|
+
* One recorded evaluation cycle by `evalId` — `GET /api/v1/alerts/{id}/agentic/evals/{evalId}`,
|
|
184
|
+
* resolvable regardless of how many cycles have run since (unlike `getAlertEvalHistory`, which
|
|
185
|
+
* only returns the most recent `limit`, capped at 60). Used by `inspectPulse`'s `get-eval`
|
|
186
|
+
* action instead of scanning a bounded history window client-side — a real correctness bug for a
|
|
187
|
+
* busy per-build alert's older cycles, fixed 2026-08-14.
|
|
188
|
+
*/
|
|
189
|
+
export declare function getAlertEval(alertId: string, evalId: string, httpClient?: PulseReadClient): Promise<AgenticEvalRecord>;
|
|
190
|
+
/** One raw per-query result row — the raw table result + transform outputs for one query within one evaluation cycle, as returned by `GET /api/v1/alerts/{id}/agentic/evals/{evalId}/results`. Hand-rolled from vnext's `agenticEvalResultRecord`. */
|
|
191
|
+
export interface AgenticEvalResultRecord {
|
|
192
|
+
queryName: string;
|
|
193
|
+
timestamp: string;
|
|
194
|
+
result: {
|
|
195
|
+
columns?: Array<{
|
|
196
|
+
name: string;
|
|
197
|
+
role?: 'key' | 'value';
|
|
198
|
+
datatype?: string;
|
|
199
|
+
}>;
|
|
200
|
+
rows?: unknown[];
|
|
201
|
+
};
|
|
202
|
+
outputs?: Record<string, unknown>;
|
|
203
|
+
queryVersion: number;
|
|
204
|
+
evalId: string;
|
|
205
|
+
trigger?: 'build' | 'schedule' | 'onDemand' | 'create';
|
|
206
|
+
}
|
|
207
|
+
/**
|
|
208
|
+
* Every raw per-query row behind one evaluation cycle — `GET
|
|
209
|
+
* /api/v1/alerts/{id}/agentic/evals/{evalId}/results`. The audit trail's last layer: `alertEvals`
|
|
210
|
+
* (`getAlertEval`/`getAlertEvalHistory`) only ever holds row-count/signal *summaries*
|
|
211
|
+
* (`AgenticQueryEvalSummary`), never the actual columns/rows a query returned. This is what lets
|
|
212
|
+
* the assistant trace a narrative's claim ("revenue dropped 18%") down to the real data it came
|
|
213
|
+
* from, instead of citing a summary of a summary. Returns `[]` (not an error) when the cycle's
|
|
214
|
+
* rows have aged past the eval record's own 90-day retention window — a real, sayable state, not
|
|
215
|
+
* "nothing happened".
|
|
216
|
+
*/
|
|
217
|
+
export declare function getAlertEvalResults(alertId: string, evalId: string, httpClient?: PulseReadClient): Promise<AgenticEvalResultRecord[]>;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { HttpClient } from '@sisense/sdk-rest-client';
|
|
2
|
+
export interface WidgetSearchOptions {
|
|
3
|
+
limit?: number;
|
|
4
|
+
type?: 'widget' | 'dashboard';
|
|
5
|
+
dashboardId?: string;
|
|
6
|
+
widgetType?: string;
|
|
7
|
+
dataSource?: string;
|
|
8
|
+
}
|
|
9
|
+
export interface WidgetSearchRequest {
|
|
10
|
+
searchString: string;
|
|
11
|
+
options?: WidgetSearchOptions;
|
|
12
|
+
}
|
|
13
|
+
/** User's access level on a result's source dashboard; mirrors Sisense share permissions. */
|
|
14
|
+
export type WidgetSearchResultPermission = 'owner' | 'edit' | 'read' | 'readNoList' | 'none';
|
|
15
|
+
export interface WidgetSearchResultItem {
|
|
16
|
+
type: 'widget' | 'dashboard';
|
|
17
|
+
id: string;
|
|
18
|
+
title: string;
|
|
19
|
+
description: string;
|
|
20
|
+
dashboardId?: string;
|
|
21
|
+
dashboardTitle?: string;
|
|
22
|
+
widgetType?: string;
|
|
23
|
+
dataSource?: string;
|
|
24
|
+
url?: string;
|
|
25
|
+
/**
|
|
26
|
+
* Rank-normalized match indicator (0,1] — reflects fused result order, not raw embedding
|
|
27
|
+
* distance. NOT a quality signal on its own; a fuzzy/lexical-only hit can still read ~1 here.
|
|
28
|
+
* Do not threshold on this field — use `cosineSimilarity` instead.
|
|
29
|
+
*/
|
|
30
|
+
similarity?: number;
|
|
31
|
+
/** Raw cosine similarity (0-1) of the vector branch. Use this for confidence thresholding. */
|
|
32
|
+
cosineSimilarity?: number;
|
|
33
|
+
permission?: WidgetSearchResultPermission;
|
|
34
|
+
metadata?: Record<string, unknown>;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Client for ai-integration's widget semantic-search endpoint. Widgets/dashboards are human-built,
|
|
38
|
+
* so a confident hit here is an inherently "verified" answer — used by the existing-answer cascade
|
|
39
|
+
* (see engines/shared/existing-answer-cascade.ts) as an alternative to full NLQ generation.
|
|
40
|
+
*/
|
|
41
|
+
export declare function searchWidgets(request: WidgetSearchRequest, httpClient?: HttpClient, abortSignal?: AbortSignal,
|
|
42
|
+
/** Sent as `x-tool-name`: the tool this call is made for. */
|
|
43
|
+
toolName?: string): Promise<WidgetSearchResultItem[]>;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { HttpClient } from '@sisense/sdk-rest-client';
|
|
2
|
+
/**
|
|
3
|
+
* The box's tool store (ai-integration, SNS-133855): the tools listed for the caller's tenant
|
|
4
|
+
* and agent. The agent is the host's interface name — the value it sends as `x-interface-name`
|
|
5
|
+
* (`STUDIO-ASSISTANT`, `ANALYTICS-ASSISTANT`, `MCP`).
|
|
6
|
+
*/
|
|
7
|
+
export declare const TOOL_STORE_API_URL_PATH = "api/v2/ai/tools";
|
|
8
|
+
/**
|
|
9
|
+
* One tool the box lists: a name at one version. A name the box supports at several versions comes
|
|
10
|
+
* once per version. `version` is absent only when the box's store has no versions at all
|
|
11
|
+
* (2026.4.1, a seeded database): see `createToolAvailability`.
|
|
12
|
+
*/
|
|
13
|
+
export interface ListedTool {
|
|
14
|
+
readonly name: string;
|
|
15
|
+
readonly version?: number;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* The tools the box lists, enabled, for this tenant and `agent`, each name at each version it
|
|
19
|
+
* supports, or `undefined` when it gives no answer: no tools endpoint (404, an older box), an error, a timeout, or an unexpected body.
|
|
20
|
+
* The caller then keeps its static list — the store is a reliability mechanism, not a security
|
|
21
|
+
* boundary (SNS-134849). An empty array is an answer: the box lists nothing.
|
|
22
|
+
*/
|
|
23
|
+
export declare function fetchToolStore(agent: string, httpClient?: HttpClient): Promise<ListedTool[] | undefined>;
|
|
24
|
+
/** {@link fetchToolStore}, memoized per instance (base URL) and agent. */
|
|
25
|
+
export declare function loadToolStore(agent: string, httpClient?: HttpClient): Promise<ListedTool[] | undefined>;
|
|
26
|
+
/**
|
|
27
|
+
* Start the read ahead of the first send, e.g. when an assistant mounts, so that send does not
|
|
28
|
+
* wait for it.
|
|
29
|
+
*/
|
|
30
|
+
export declare function prefetchToolStore(agent: string, httpClient?: HttpClient): void;
|
|
31
|
+
/** Forget every read, e.g. in tests. */
|
|
32
|
+
export declare function resetToolStoreCache(): void;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { HttpClient } from '@sisense/sdk-rest-client';
|
|
2
|
+
/** Minimal shape this service needs from `GET /api/v1/users` — not the full `user` swagger definition. */
|
|
3
|
+
export interface UserLookupResult {
|
|
4
|
+
_id: string;
|
|
5
|
+
email: string;
|
|
6
|
+
userName?: string;
|
|
7
|
+
firstName?: string;
|
|
8
|
+
lastName?: string;
|
|
9
|
+
}
|
|
10
|
+
/** Minimal shape this service needs from `GET /api/v1/groups` — not the full `group` swagger definition. */
|
|
11
|
+
export interface GroupLookupResult {
|
|
12
|
+
_id: string;
|
|
13
|
+
name: string;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Thrown when a users/groups lookup 403s — both endpoints are declared
|
|
17
|
+
* `x-roles-allowed: tenantAdmin,admin` in identity-service's swagger (confirmed for both `v1`
|
|
18
|
+
* and the legacy `v0.9` routes PrismWebClient's own Pulse-sharing autocomplete calls), but the
|
|
19
|
+
* caller's actual effective permission may be wider than that declaration (RBAC grants can differ
|
|
20
|
+
* from the textual role list) — this is unconfirmed either way, so a 403 is surfaced as an
|
|
21
|
+
* actionable message rather than an opaque failure (SNS-132805, see
|
|
22
|
+
* PULSE_AGENTIC_ALERTS_ARCHITECTURE.md's party-resolution note).
|
|
23
|
+
*/
|
|
24
|
+
export declare class UserGroupLookupForbiddenError extends Error {
|
|
25
|
+
constructor(kind: 'user' | 'group');
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Resolve a user by exact email — used to turn "add jane@acme.com" into a party id for
|
|
29
|
+
* `update-workflow`. Returns `undefined` on no match (not an error: the caller decides whether
|
|
30
|
+
* "no such user" is fatal).
|
|
31
|
+
*/
|
|
32
|
+
export declare function findUserByEmail(email: string, httpClient?: HttpClient): Promise<UserLookupResult | undefined>;
|
|
33
|
+
/**
|
|
34
|
+
* Resolve a group (or ad-group) by name search — used to turn "add the Finance group" into a
|
|
35
|
+
* party id. Returns every match; the caller (engine) decides how to handle more than one.
|
|
36
|
+
*/
|
|
37
|
+
export declare function findGroupsByName(name: string, httpClient?: HttpClient): Promise<GroupLookupResult[]>;
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/**
|
|
3
|
+
* Registry of `loadSkill` operational playbooks — host-agnostic so any host (sdk-assistant,
|
|
4
|
+
* an MCP server, a custom integration) can register the `loadSkill` tool and defer the same
|
|
5
|
+
* markdown, instead of paying its cost inline in every tool description on every turn. Hosts
|
|
6
|
+
* pick a subset via `createLoadSkillSchema(allowedSkills)` matching the tools they register —
|
|
7
|
+
* the same pattern as `buildQuerySchema` / `getDataSourceFieldsSchema`. Studio wraps that
|
|
8
|
+
* schema in `createLoadSkillTool` (`libs/sdk-assistant/.../load-skill-function.ts`).
|
|
9
|
+
*
|
|
10
|
+
* Each skill carries its own trigger: `SKILL_WHEN` is rendered into the `loadSkill` tool
|
|
11
|
+
* description by `createLoadSkillToolDescription`, so the model learns when to load a skill
|
|
12
|
+
* from the skill itself on every host — including skills triggered by a kind of question
|
|
13
|
+
* (`describeDashboard`) rather than by a tool the model is about to call. The verbs match the
|
|
14
|
+
* prompt `<skills>` blocks and the tool preconditions, so the surfaces do not disagree.
|
|
15
|
+
*/
|
|
16
|
+
export declare const SKILL_NAMES: readonly ["buildQuery", "buildChart", "buildDashboard", "authorPulse", "inspectPulse", "describeDashboard"];
|
|
17
|
+
export type SkillName = (typeof SKILL_NAMES)[number];
|
|
18
|
+
/** One trigger line per skill — a `Record` so a new skill cannot ship without one. */
|
|
19
|
+
export declare const SKILL_WHEN: Record<SkillName, string>;
|
|
20
|
+
export interface SkillEntry {
|
|
21
|
+
name: SkillName;
|
|
22
|
+
when: string;
|
|
23
|
+
}
|
|
24
|
+
/** The registry as `{ name, when }` rows, in `SKILL_NAMES` order. */
|
|
25
|
+
export declare const SKILLS: readonly SkillEntry[];
|
|
26
|
+
/**
|
|
27
|
+
* Each skill as a host that serves on-demand sections returns it: the core text, which
|
|
28
|
+
* lists its sections. Only a host that also registers `loadSkill` with
|
|
29
|
+
* `createLoadSkillSchema(skills, { sections: true })` and serves `SKILL_SECTIONS` may use
|
|
30
|
+
* it (SNS-135696).
|
|
31
|
+
*/
|
|
32
|
+
export declare const SKILL_CORE_CONTENT: Record<SkillName, string>;
|
|
33
|
+
/** Each skill's whole guidance — what every host that does not serve sections returns. */
|
|
34
|
+
export declare const SKILL_CONTENT: Record<SkillName, string>;
|
|
35
|
+
/**
|
|
36
|
+
* Parts of a skill served only on request, `loadSkill({ skillName, section })`, so the
|
|
37
|
+
* skill itself stays small (SNS-135696). The skill's own text lists its sections and
|
|
38
|
+
* when to load each; a section's text is replayed in the history only once it is used.
|
|
39
|
+
*/
|
|
40
|
+
export declare const SKILL_SECTIONS: Partial<Record<SkillName, Record<string, string>>>;
|
|
41
|
+
/** Every section id any of `allowedSkills` has, sorted. */
|
|
42
|
+
export declare function sectionNames(allowedSkills: readonly SkillName[]): string[];
|
|
43
|
+
export declare function getSkill(name: SkillName): string;
|
|
44
|
+
/**
|
|
45
|
+
* The authorPulse and inspectPulse playbooks in the atomic Pulse tools' words (SNS-136028):
|
|
46
|
+
* `createPulse` where the composite playbook says `create`. Kept out of `SKILL_NAMES`, because the
|
|
47
|
+
* assistants' `loadSkill` serves every name there and the assistants still call the composite
|
|
48
|
+
* tools; a host that registers the atomic tools serves these in place of `authorPulse` and
|
|
49
|
+
* `inspectPulse`. When the assistants move to the atomic tools, these replace the composite ones.
|
|
50
|
+
*/
|
|
51
|
+
export declare const ATOMIC_SKILL_NAMES: readonly ["authorPulseAtomic", "inspectPulseAtomic"];
|
|
52
|
+
export type AtomicSkillName = (typeof ATOMIC_SKILL_NAMES)[number];
|
|
53
|
+
export declare const ATOMIC_SKILL_CONTENT: Record<AtomicSkillName, string>;
|
|
54
|
+
export declare function formatAllowedSkills(allowedSkills: readonly SkillName[]): string;
|
|
55
|
+
/**
|
|
56
|
+
* Canonical tool description for loadSkill — the mechanism, not the list. Hosts should prefer
|
|
57
|
+
* `createLoadSkillToolDescription(allowedSkills)`, which appends each allowed skill's trigger.
|
|
58
|
+
*/
|
|
59
|
+
export declare const loadSkillToolDescription = "Load detailed operational guidance for a workflow or a kind of question. Always call this before starting work, or answering a question, that a skill covers.";
|
|
60
|
+
/**
|
|
61
|
+
* `loadSkillToolDescription` plus one `name — when` line per allowed skill, in allowlist
|
|
62
|
+
* order. Only the host's own skills are listed, so the model is never told to load a playbook
|
|
63
|
+
* the schema would reject.
|
|
64
|
+
*/
|
|
65
|
+
export declare function createLoadSkillToolDescription(allowedSkills: readonly SkillName[]): string;
|
|
66
|
+
/**
|
|
67
|
+
* Hosts pass the skill names they actually register so the model cannot request a playbook
|
|
68
|
+
* for a tool that is not on this host (e.g. MCP omits buildDashboard and Pulse skills).
|
|
69
|
+
*/
|
|
70
|
+
export declare function createLoadSkillSchema(allowedSkills: readonly SkillName[], { sections }?: {
|
|
71
|
+
sections?: boolean;
|
|
72
|
+
}): z.ZodObject<{
|
|
73
|
+
skillName: z.ZodEnum<{
|
|
74
|
+
buildChart: "buildChart";
|
|
75
|
+
buildDashboard: "buildDashboard";
|
|
76
|
+
buildQuery: "buildQuery";
|
|
77
|
+
inspectPulse: "inspectPulse";
|
|
78
|
+
authorPulse: "authorPulse";
|
|
79
|
+
describeDashboard: "describeDashboard";
|
|
80
|
+
}>;
|
|
81
|
+
}, z.core.$strip>;
|
|
82
|
+
export type LoadSkillParams = z.infer<ReturnType<typeof createLoadSkillSchema>>;
|
|
83
|
+
export declare const loadSkillSchema: z.ZodObject<{
|
|
84
|
+
skillName: z.ZodEnum<{
|
|
85
|
+
buildChart: "buildChart";
|
|
86
|
+
buildDashboard: "buildDashboard";
|
|
87
|
+
buildQuery: "buildQuery";
|
|
88
|
+
inspectPulse: "inspectPulse";
|
|
89
|
+
authorPulse: "authorPulse";
|
|
90
|
+
describeDashboard: "describeDashboard";
|
|
91
|
+
}>;
|
|
92
|
+
}, z.core.$strip>;
|
|
93
|
+
/**
|
|
94
|
+
* Appended to the buildQuery skill by hosts that register the data model map tools
|
|
95
|
+
* (SNS-131459) — never part of `SKILL_CONTENT`, so the skill is byte-identical when the
|
|
96
|
+
* map is off.
|
|
97
|
+
*/
|
|
98
|
+
export declare const BUILD_QUERY_DATAMODEL_GRAPH_ADDENDUM: string;
|
|
99
|
+
/**
|
|
100
|
+
* Appended after BUILD_QUERY_DATAMODEL_GRAPH_ADDENDUM only when the data model map's
|
|
101
|
+
* widget layer is on (config `widgetsEnabled`), so with widgets off the skill text is
|
|
102
|
+
* byte-identical to the map-only text.
|
|
103
|
+
*/
|
|
104
|
+
export declare const BUILD_QUERY_DATAMODEL_WIDGETS_ADDENDUM: string;
|
|
105
|
+
/**
|
|
106
|
+
* Appended after BUILD_QUERY_DATAMODEL_GRAPH_ADDENDUM whenever the data model map is on
|
|
107
|
+
* (SNS-131459): how to rerun or learn from verified answers. Says nothing about widgets.
|
|
108
|
+
*/
|
|
109
|
+
export declare const BUILD_QUERY_DATAMODEL_VERIFIED_ADDENDUM: string;
|
|
110
|
+
/**
|
|
111
|
+
* Appended after the map addendum (and the widget addendum) only when the config's
|
|
112
|
+
* `pulseEnabled` is on: how to use metrics watched by Pulse alerts. With Pulse off the skill
|
|
113
|
+
* text is byte-identical to today.
|
|
114
|
+
*/
|
|
115
|
+
export declare const BUILD_QUERY_DATAMODEL_PULSE_ADDENDUM: string;
|
|
116
|
+
/**
|
|
117
|
+
* Appended to the authorPulse skill only when the data model map and its Pulse layer are on
|
|
118
|
+
* (SNS-131459 §6.3): how to use `pulseKnowledge` (watched formulas, company ranges) while authoring.
|
|
119
|
+
* Never part of `SKILL_CONTENT`, so the skill is byte-identical when Pulse is off.
|
|
120
|
+
*/
|
|
121
|
+
export declare const AUTHOR_PULSE_PULSE_KNOWLEDGE_ADDENDUM: string;
|
|
122
|
+
/**
|
|
123
|
+
* Appended to the describeDashboard skill by the dashboard host when the data model map is on
|
|
124
|
+
* (SNS-131459): questions about the business go to buildQuery, not to the description. Never
|
|
125
|
+
* part of `SKILL_CONTENT`, so the skill is byte-identical when the map is off.
|
|
126
|
+
*/
|
|
127
|
+
export declare const DESCRIBE_DASHBOARD_DATAMODEL_GRAPH_ADDENDUM: string;
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { ListedTool } from '../services/tool-store/tool-store-service';
|
|
2
|
+
/**
|
|
3
|
+
* Every sdk-ai-core tool: the names a skill's text can depend on (`skillRequiredTools`).
|
|
4
|
+
* `loadSkill` is technical, and `TOOL_NAME_AGENT` / `TOOL_NAME_COMPACT_HISTORY` are
|
|
5
|
+
* `x-tool-name` labels, not tools.
|
|
6
|
+
*/
|
|
7
|
+
export declare const SDK_TOOL_NAMES: readonly string[];
|
|
8
|
+
/** A tool as a host implements it: the catalog name and the one version it implements. */
|
|
9
|
+
export interface ImplementedTool {
|
|
10
|
+
readonly name: string;
|
|
11
|
+
readonly version: number;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Tools whose availability the box's tool store decides (SNS-134850, SNS-136214): every
|
|
15
|
+
* sdk-ai-core tool the catalog certifies, at the version this build implements (the latest
|
|
16
|
+
* prototype). Any other tool — one a host defines itself without `certified` — is offered whatever
|
|
17
|
+
* the store says; a host passes its own certified tools to `createToolAvailability`.
|
|
18
|
+
*/
|
|
19
|
+
export declare const CONTROLLED_TOOLS: readonly ImplementedTool[];
|
|
20
|
+
/** The names of {@link CONTROLLED_TOOLS}. */
|
|
21
|
+
export declare const CONTROLLED_TOOL_NAMES: readonly string[];
|
|
22
|
+
/**
|
|
23
|
+
* What a 2026.4.1 box's store controls: the tools its database was seeded with (ai-integration
|
|
24
|
+
* release/2026.4.1, `ToolsSeedMigration`). Such a box lists no versions, and a tool it was never
|
|
25
|
+
* seeded with is missing from its list without being disabled, so only these are decided there.
|
|
26
|
+
* Frozen: the boxes it describes do not change.
|
|
27
|
+
*/
|
|
28
|
+
export declare const TOOLS_SEEDED_ON_2026_4_1_BOXES: readonly string[];
|
|
29
|
+
/** Whether a tool may be offered, as far as the box's tool store goes. */
|
|
30
|
+
export type ToolAvailability = (toolName: string) => boolean;
|
|
31
|
+
/**
|
|
32
|
+
* A controlled tool is available only when the box lists it at the version the host implements;
|
|
33
|
+
* a box that lists the name at other versions only does not allow it. Any other tool always is.
|
|
34
|
+
*
|
|
35
|
+
* A 2026.4.1 box lists no versions (every record without one): there a controlled tool is decided
|
|
36
|
+
* by name at version 1, and only when that box was seeded with it (`TOOLS_SEEDED_ON_2026_4_1_BOXES`), so a
|
|
37
|
+
* newer client keeps every tool such a box never knew. An empty list is an answer either way and
|
|
38
|
+
* withholds every controlled tool.
|
|
39
|
+
*
|
|
40
|
+
* @param boxTools - the box's list, each name at each version it supports; `undefined` when the
|
|
41
|
+
* box gave no answer, which restricts nothing: the host keeps its static list
|
|
42
|
+
* @param controlled - the tools the store decides, each at the version the host implements; one
|
|
43
|
+
* entry per name
|
|
44
|
+
* @throws Error when `controlled` names a tool twice
|
|
45
|
+
*/
|
|
46
|
+
export declare function createToolAvailability(boxTools: readonly ListedTool[] | undefined, controlled?: readonly ImplementedTool[]): ToolAvailability;
|
|
47
|
+
/**
|
|
48
|
+
* For a host that implements a tool at several versions (mcp-service talks to boxes of many
|
|
49
|
+
* releases): the newest of them the box lists, or `undefined` when the box lists none of them and
|
|
50
|
+
* the tool must not be offered.
|
|
51
|
+
*
|
|
52
|
+
* @param boxTools - the box's list; a record without a version (a 2026.4.1 box) counts as version 1
|
|
53
|
+
* @param name - the tool
|
|
54
|
+
* @param implemented - the versions the host implements
|
|
55
|
+
*/
|
|
56
|
+
export declare function newestListedVersion(boxTools: readonly ListedTool[], name: string, implemented: readonly number[]): number | undefined;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { ModelMessage, Tool } from 'ai';
|
|
2
|
+
import { SkillName } from '../skills';
|
|
3
|
+
import { ToolAvailability } from './controlled-tools';
|
|
4
|
+
import { ServedSkills, ToolAvailabilityResolution } from './resolve-tool-availability';
|
|
5
|
+
/** The text a `loadSkill` serves per skill section, e.g. `{ buildChart: { dualAxis } }`. */
|
|
6
|
+
export type ServedSections = Partial<Record<SkillName, Record<string, string>>>;
|
|
7
|
+
/**
|
|
8
|
+
* Mark a `loadSkill` tool with the text it serves per skill, so `offerTools` can check each
|
|
9
|
+
* skill's required tools on every send and narrow the tool to the skills that load. A host
|
|
10
|
+
* that serves on-demand sections passes them too: that is how `offerTools` knows to keep
|
|
11
|
+
* the `section` parameter, without reading the schema (SNS-135696). Enumerable, so wrappers
|
|
12
|
+
* that spread the tool keep it.
|
|
13
|
+
*/
|
|
14
|
+
export declare function withServedSkills<T extends object>(loadSkillTool: T, servedSkills: ServedSkills, servedSections?: ServedSections): T;
|
|
15
|
+
/** The sections a `withServedSkills` tool serves; `undefined` when it serves none. */
|
|
16
|
+
export declare function getServedSections(tool: unknown): ServedSections | undefined;
|
|
17
|
+
/** The skills a `withServedSkills` tool serves; `undefined` for any other tool. */
|
|
18
|
+
export declare function getServedSkills(tool: unknown): ServedSkills | undefined;
|
|
19
|
+
export interface OfferedTools {
|
|
20
|
+
tools: Record<string, Tool>;
|
|
21
|
+
resolution: ToolAvailabilityResolution;
|
|
22
|
+
/** The text `loadSkill` serves per skill this send. */
|
|
23
|
+
servedSkills: ServedSkills;
|
|
24
|
+
/** The text `loadSkill` serves per section this send; empty for a host without sections. */
|
|
25
|
+
servedSections: ServedSections;
|
|
26
|
+
/** The host's tools this send does not offer. */
|
|
27
|
+
withdrawn: string[];
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The tools to send the model (SNS-134850): `tools` without the ones `resolveToolAvailability`
|
|
31
|
+
* withdraws, `loadSkill` narrowed to the skills that load, and every description and skill
|
|
32
|
+
* text without the sentences about a withdrawn tool (`dropWithdrawnText`). A `loadSkill`
|
|
33
|
+
* without `withServedSkills` is a host's own and passes as is.
|
|
34
|
+
*/
|
|
35
|
+
export declare function offerTools(tools: Record<string, Tool>, isAvailable: ToolAvailability): OfferedTools;
|
|
36
|
+
/**
|
|
37
|
+
* What the model must hear about skills it loaded earlier in this chat whose text no longer
|
|
38
|
+
* applies: the session's context changed since (another dashboard, the data model map turned
|
|
39
|
+
* on, a tool withdrawn), so a skill or a section now serves a different text, or no longer
|
|
40
|
+
* loads. `undefined` when nothing changed. The last load of each skill and of each section
|
|
41
|
+
* counts; a load whose result was compacted away is only checked for availability. A section
|
|
42
|
+
* is compared with its own served text, never with its skill's (SNS-135696).
|
|
43
|
+
*/
|
|
44
|
+
export declare function staleSkillsInstruction(messages: readonly ModelMessage[], servedSkills: ServedSkills, loadableSkills: readonly SkillName[], servedSections?: ServedSections): string | undefined;
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import { SkillName } from '../skills';
|
|
2
|
+
import { ToolAvailability } from './controlled-tools';
|
|
3
|
+
/** The names out of `vocabulary` that `text` mentions, as whole words. */
|
|
4
|
+
export declare function mentionedTools(text: string, vocabulary: readonly string[]): string[];
|
|
5
|
+
/**
|
|
6
|
+
* Tools a skill mentions without depending on them, so its text alone would over-require:
|
|
7
|
+
* a higher-level tool it points on to, an optional one, or one it warns against. Every other
|
|
8
|
+
* sdk-ai-core tool the served text mentions is required (`skillRequiredTools`).
|
|
9
|
+
*/
|
|
10
|
+
export declare const SKILL_NOT_REQUIRED_TOOLS: Readonly<Record<SkillName, readonly string[]>>;
|
|
11
|
+
/**
|
|
12
|
+
* Tools that act on another tool's output, offered only with it. A tool that shares its name
|
|
13
|
+
* with a served skill also needs that skill loadable (`resolveToolAvailability`).
|
|
14
|
+
*/
|
|
15
|
+
export declare const TOOL_REQUIREMENTS: Readonly<Partial<Record<string, readonly string[]>>>;
|
|
16
|
+
/**
|
|
17
|
+
* The tools a skill cannot work without: every sdk-ai-core tool its **served** text mentions —
|
|
18
|
+
* after the host's addenda and rewrites, so a session that serves a different text (the data
|
|
19
|
+
* model map) is checked against the tools that text names — minus `SKILL_NOT_REQUIRED_TOOLS`.
|
|
20
|
+
*/
|
|
21
|
+
export declare function skillRequiredTools(skill: SkillName, servedText: string, vocabulary?: readonly string[]): string[];
|
|
22
|
+
/** The text a host serves for each skill its `loadSkill` offers. */
|
|
23
|
+
export type ServedSkills = Partial<Record<SkillName, string>>;
|
|
24
|
+
export interface ToolAvailabilityInput {
|
|
25
|
+
/** The tools the host offers, in its order. */
|
|
26
|
+
tools: readonly string[];
|
|
27
|
+
/** The skills its `loadSkill` serves; none when it registers no `loadSkill`. */
|
|
28
|
+
servedSkills?: ServedSkills;
|
|
29
|
+
isAvailable: ToolAvailability;
|
|
30
|
+
/** The tool names a skill's text can depend on; the sdk-ai-core tools by default. */
|
|
31
|
+
vocabulary?: readonly string[];
|
|
32
|
+
/**
|
|
33
|
+
* The tools each tool needs, `TOOL_REQUIREMENTS` by default. A host that offers tools of its
|
|
34
|
+
* own passes the default plus their entries.
|
|
35
|
+
*/
|
|
36
|
+
requirements?: Readonly<Partial<Record<string, readonly string[]>>>;
|
|
37
|
+
}
|
|
38
|
+
export interface ToolAvailabilityResolution {
|
|
39
|
+
/** The tools to offer, in input order. */
|
|
40
|
+
offered: string[];
|
|
41
|
+
/** Tools not offered, and the tools each misses (itself, when the store does not list it). */
|
|
42
|
+
withdrawn: {
|
|
43
|
+
tool: string;
|
|
44
|
+
missingTools: string[];
|
|
45
|
+
}[];
|
|
46
|
+
/** Loadable skills, in `SKILL_NAMES` order. */
|
|
47
|
+
skills: SkillName[];
|
|
48
|
+
/** Served skills that cannot load, and the required tools each misses. */
|
|
49
|
+
rejectedSkills: {
|
|
50
|
+
skill: SkillName;
|
|
51
|
+
missingTools: string[];
|
|
52
|
+
}[];
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Which tools to offer and which skills `loadSkill` may serve (SNS-134850), as a cascade:
|
|
56
|
+
*
|
|
57
|
+
* - A tool the store does not allow is not offered.
|
|
58
|
+
* - A skill loads only when every tool it requires is offered.
|
|
59
|
+
* - A tool is offered only when its requirements are (`TOOL_REQUIREMENTS`, unless the host passes
|
|
60
|
+
* its own), and — when a served skill shares its
|
|
61
|
+
* name — that skill loads. So without `getDataPreview`, the buildQuery skill does not load,
|
|
62
|
+
* buildQuery is not offered, and neither is buildChart, which needs its `queryId`.
|
|
63
|
+
* - `loadSkill` is offered only while some skill loads.
|
|
64
|
+
*
|
|
65
|
+
* The greatest fixpoint: start from every allowed tool and drop, round by round, each one whose
|
|
66
|
+
* requirements are not met, until a round drops nothing.
|
|
67
|
+
*/
|
|
68
|
+
export declare function resolveToolAvailability({ tools, servedSkills, isAvailable, vocabulary, requirements, }: ToolAvailabilityInput): ToolAvailabilityResolution;
|