react-semaphor 0.1.537 → 0.1.538

package/dist/types/shared/assistant-context/saved-dashboard-context.d.ts

@@ -0,0 +1,130 @@
+import { TCard, TDashboard } from '../../lib/types/common-types.js';
+import { CardViewStateMap } from '../../lib/dashboard-view-state/index.js';
+import { SemanticExecutionPayload } from '../../lib/types/semantic-runtime-types.js';
+import { CalendarContext } from '../report-runtime-context/index.js';
+import { ViewerStoreInputValues } from '../../lib/dashboard-viewer/compatibility-input-storage.js';
+import { DashboardCardExecutionSnapshotResult } from '../../lib/query-context/build-dashboard-execution-snapshot.js';
+import { TransientInputContext } from '../../lib/dashboard-inputs/transient-input-context.js';
+import { DashboardCardLocation } from '../dashboard-authoring/document-section-cards.js';
+import { AssistantContext } from '../assistant-protocol/context.js';
+import { AssistantCardRequest, AssistantCardUnavailable, AssistantCardUnavailableReason } from '../assistant-protocol/request.js';
+/**
+ * A saved dashboard as a fresh viewer opens it (saved defaults, no bookmark),
+ * as the assistant's context: the regression set's dashboard cases
+ * (analytics agent Plan 1, ledger D3a-9). Each step is the owner the browser
+ * uses: the viewer baseline, the store's input values, the card's location,
+ * the card's snapshot where it sits, and the projection.
+ */
+/** Where a case puts the viewer. */
+export type SavedDashboardPlace = {
+    /** The sheet on screen: by default the asked-about card's sheet, else the first sheet. */
+    sheetId?: string;
+    /** The card asked about. */
+    cardId?: string;
+    /** Drill paths by card. */
+    cardViewState?: CardViewStateMap;
+};
+/** The store's input values plus drill paths: what a card's snapshot is built from. */
+export type CardRuntimeValues = ViewerStoreInputValues & {
+    cardViewState: CardViewStateMap;
+};
+export declare function projectSavedDashboardContext(input: {
+    dashboard: TDashboard;
+    place: SavedDashboardPlace;
+    semanticExecutionPayload: SemanticExecutionPayload | undefined;
+    /** The report calendar the dashboard opens with; its zone is the viewer's. */
+    calendar: CalendarContext;
+}): AssistantContext;
+/**
+ * What a browser opening the saved dashboard at `place` sends with a message:
+ * the context and, for an asked-about card, its replay fields, both from the
+ * one snapshot (ledger P3-92). The regression set sends exactly this.
+ */
+export declare function projectSavedDashboardTurn(input: {
+    dashboard: TDashboard;
+    place: SavedDashboardPlace;
+    semanticExecutionPayload: SemanticExecutionPayload | undefined;
+    calendar: CalendarContext;
+}): {
+    context: AssistantContext;
+    cardReplay?: AssistantCardReplayFields;
+};
+/** The turn request's fields for an asked-about card: its request, or why it has none. */
+export type AssistantCardReplayFields = {
+    selectedCardRequest: AssistantCardRequest;
+} | {
+    selectedCardUnavailable: AssistantCardUnavailable;
+};
+/**
+ * The asked-about card's replay fields, where the card sits on the dashboard,
+ * by the rule an external client's saved card follows (`cardReplayOf`). The
+ * browser sends these with every message about a card (D3b-2, P3-92).
+ */
+export declare function assistantCardReplayFields(input: {
+    dashboard: TDashboard | undefined;
+    cardId: string;
+    snapshot: DashboardCardExecutionSnapshotResult | 'pending';
+    /** The card the snapshot runs when it is not the dashboard's copy: the editor's draft (D5-3). */
+    card?: Pick<TCard, 'type'>;
+}): AssistantCardReplayFields;
+/**
+ * A card's execution snapshot outside the store, where the card sits, with
+ * the arguments its store adapter passes: the card is its own override, and a
+ * document section card runs as its section does on the page.
+ */
+export declare function buildLocatedCardSnapshot(input: {
+    dashboard: TDashboard;
+    location: DashboardCardLocation;
+    runtimeValues: CardRuntimeValues;
+    semanticExecutionPayload: SemanticExecutionPayload | undefined;
+    /** The report calendar the card runs in. */
+    calendar: CalendarContext;
+    /** What a drill-through carried onto this dashboard; a fresh viewer has none. */
+    transientContexts?: readonly TransientInputContext[];
+    /** Also carry the card's request (D3b-2). */
+    withRequest?: boolean;
+}): DashboardCardExecutionSnapshotResult;
+/** Why a saved card has no request to replay. */
+export type SavedCardRequestRefusal = 'card_not_found' | Exclude<AssistantCardUnavailableReason, 'pending'>;
+/**
+ * A card's request for a server replay, or why it has none: one rule for an
+ * external client's saved card (`buildSavedCardRequest`) and the browser's
+ * asked-about card (analytics agent Plan 1, D3b-2, ledger P3-92). A card in
+ * a Document section runs with its page's inputs, a Matrix card on its window
+ * path; a card whose filter mapping is blocked, or with no snapshot, cannot
+ * run; a card with no query (text) has nothing to run.
+ */
+export declare function cardReplayOf(input: {
+    /** The card where it sits; its kind decides before its snapshot does. */
+    card: Pick<TCard, 'type'> | undefined;
+    snapshot: DashboardCardExecutionSnapshotResult | 'pending';
+    documentSection: boolean;
+}): {
+    status: 'ready';
+    request: AssistantCardRequest;
+} | {
+    status: 'unavailable';
+    reason: AssistantCardUnavailableReason;
+    message?: string;
+};
+/**
+ * A saved card's request as a fresh viewer opens it (saved defaults, no
+ * bookmark, no drill), for an external client's `fromCard` replay
+ * (analytics agent Plan 1, Phase 3b, D3b-2). The same owners as the context:
+ * the viewer baseline, the store's input values, the card's snapshot with its
+ * request, and the server-request owner CSV export shares. Pure; the caller
+ * loads the dashboard, its semantic payload and calendar, and checks access.
+ */
+export declare function buildSavedCardRequest(input: {
+    dashboard: TDashboard;
+    cardId: string;
+    semanticExecutionPayload: SemanticExecutionPayload | undefined;
+    calendar: CalendarContext;
+}): {
+    status: 'ready';
+    request: AssistantCardRequest;
+} | {
+    status: 'refused';
+    reason: SavedCardRequestRefusal;
+    message?: string;
+};

package/dist/types/shared/assistant-protocol/add-to-dashboard.d.ts

@@ -0,0 +1,17 @@
+import { TChartType } from '../../lib/charts/types.js';
+import { TCard } from '../../lib/types/common-types.js';
+import { VisualKind } from '../analytics-protocol/visual-choice.js';
+/**
+ * Add to dashboard (analytics agent Plan 1, Phase 7a, D7-4, D7-5): a result
+ * carries its card form, the one its execution recorded, and the browser adds
+ * it through the dashboard reducer (`applyDashboardOperations`) with no
+ * request: the turn that showed the result already checked who may see it.
+ */
+/** The card type each chat kind becomes. */
+export declare const ASSISTANT_CARD_TYPES: Record<VisualKind, TChartType>;
+/**
+ * A result's card, as its execution recorded it: a governed answer's
+ * compiled config and data source, or an advanced SQL answer's statement and
+ * Python step. Title, type and ids come at Add.
+ */
+export type AssistantArtifactCardForm = Pick<TCard, 'connectionId' | 'config' | 'dataSource' | 'sql' | 'python'>;

package/dist/types/shared/assistant-protocol/artifact.d.ts

@@ -0,0 +1,63 @@
+import { SemaphorDialect, SemaphorResultColumn, SemaphorSourceRef } from '../analytics-protocol/contracts.js';
+import { VisualChoiceInput, VisualKind, VisualSpec } from '../analytics-protocol/visual-choice.js';
+import { AssistantArtifactCardForm } from './add-to-dashboard.js';
+/**
+ * An answer's artifact (analytics agent Plan 1, spec 2.5, Phase 4): rows from
+ * a governed result the model chose to show (`show_result`), built only on
+ * the server from that result, never from model text (D4-2, D4-3). Stored on
+ * the turn as an `artifact` part, so history shows it as it streamed. Its
+ * visual is decided on the server by `chooseVisual` over the same rows (4b).
+ */
+export type AssistantArtifact = {
+    version: 1;
+    /** Unique within the conversation. */
+    artifactId: string;
+    title: string;
+    /** What it opens as: `chooseVisual`'s default, or the kind the model asked for (D4b-2, D4b-3). */
+    visual: VisualSpec;
+    /** Kinds the toggle offers, default first. */
+    eligible: VisualKind[];
+    columns: SemaphorResultColumn[];
+    /** At most ASSISTANT_LIMITS.artifactRecords. */
+    records: Array<Record<string, unknown>>;
+    /** Rows in the whole result. */
+    rowCount: number;
+    status: {
+        /** Governed semantic analysis; false for advanced SQL. */
+        governed: boolean;
+        /** False when the result answered only part of the question. */
+        complete: boolean;
+        /** True when the result has more rows than `records` (or the query hit its row limit). */
+        truncated: boolean;
+    };
+    /** How it was calculated, for the viewer; display only, never executed. */
+    origin: {
+        kind: 'fields';
+        source?: SemaphorSourceRef;
+        measures: string[];
+        dimensions: string[];
+        filters: string[];
+    } | {
+        kind: 'sql';
+        dialect?: SemaphorDialect;
+        sql: string;
+    };
+    /** The executed query behind it, resolved only on the server against the owner-checked record. */
+    queryRef: {
+        conversationId: string;
+        turnId: string;
+        artifactId: string;
+    };
+    /**
+     * Its card, for Add to dashboard (Phase 7a, D7-4): the form its execution
+     * recorded. Absent: not addable (a period change, a snapshot, a replay of a
+     * card already on the dashboard, a result stored before Phase 7a). For the
+     * browser only; the model never reads message parts (AG-INV-5).
+     */
+    card?: AssistantArtifactCardForm;
+};
+/**
+ * What `chooseVisual` reads from an artifact: the server deciding its visual
+ * and the toggle asking for another kind read the same input.
+ */
+export declare function visualInputOf(artifact: Pick<AssistantArtifact, 'columns' | 'records' | 'rowCount' | 'status'>): VisualChoiceInput;

package/dist/types/shared/assistant-protocol/availability.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Whether the assistant is available (analytics agent Plan 1, spec 2.3,
+ * module M2). The browser hides every entry point on `available: false`; the
+ * server refuses with the same reason (AG-D13, AG-INV-7).
+ */
+export type AssistantAvailabilityInput = {
+    /** Feature switches: resolved project features (server), or `projectFeatures.features` from the token (browser). */
+    features: {
+        aiFeatures?: boolean;
+        assistant?: boolean;
+        /** The deleted assistant's switch, still stored in some policies. */
+        dashboardAssistant?: boolean;
+    };
+    /** The token's `config.assistant.enabled`, as `readAssistantTokenConfig` reads it (the old flag included). */
+    config: {
+        enabled: boolean | undefined;
+    };
+    identity: {
+        orgUserId?: string;
+        tenantId?: string;
+        endUserId?: string;
+    };
+    /** Whether a model key is configured. Server: resolveAssistantModel() !== undefined. Browser: true. */
+    modelConfigured: boolean;
+};
+export type AssistantUnavailableReason = 'not_configured' | 'ai_features_off' | 'assistant_off' | 'not_enabled_for_token' | 'no_user_identity';
+export type AssistantAvailability = {
+    available: true;
+} | {
+    available: false;
+    reason: AssistantUnavailableReason;
+};
+/**
+ * Pure. Checked in order; the first that fails is the reason: model key,
+ * master switch, assistant switch (or the old switch when it is unset), token
+ * flag (`config.assistant.enabled`, or the old flag when it is unset), user
+ * identity.
+ */
+export declare function resolveAssistantAvailability(input: AssistantAvailabilityInput): AssistantAvailability;