react-semaphor 0.1.537 → 0.1.539

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

@@ -0,0 +1,38 @@
+import { SemaphorSourceRef } from '../analytics-protocol/contracts.js';
+import { AssistantPart } from './parts.js';
+/** How a stored turn ended; `running` while it is answering, `interrupted` when its process died. */
+export type TurnOutcome = 'running' | 'completed' | 'stopped' | 'failed' | 'refused' | 'interrupted';
+/** For the full page: one of the caller's conversations from the last 24 hours. */
+export type AssistantConversationSummary = {
+    conversationId: string;
+    /** The first message, trimmed to 80 characters. */
+    title: string;
+    dashboardId?: string;
+    lastActivityAt: string;
+    expiresAt: string;
+    turnCount: number;
+};
+/**
+ * What opening a conversation returns (Phase 3c, D3c-5): the turns as the
+ * transcript shows them. Never the context, tool calls, card request,
+ * executed queries or provider replay (AG-INV-5).
+ */
+export type AssistantConversationDetail = {
+    conversationId: string;
+    addedSources: SemaphorSourceRef[];
+    turns: Array<{
+        turnId: string;
+        startedAt: string;
+        message: string;
+        /** Shown through the one stored-part mapping the stream uses (D3c-6, `transcript.ts`). */
+        parts: AssistantPart[];
+        outcome: TurnOutcome;
+    }>;
+};
+export declare const ASSISTANT_LAYOUTS: readonly ["docked-right", "docked-left", "centered", "full-page"];
+/** Where the assistant opens. Token config `assistant.layout` sets the embed default (AG-D21). */
+export type AssistantLayout = (typeof ASSISTANT_LAYOUTS)[number];
+export declare function isAssistantLayout(value: unknown): value is AssistantLayout;
+/** Default name in customer-facing text; token config `assistant.name` overrides it (AG-D19). */
+export declare const DEFAULT_ASSISTANT_NAME = "Assistant";
+export declare const ASSISTANT_NAME_MAX_CHARS = 40;

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

@@ -0,0 +1,16 @@
+/**
+ * `react-semaphor/assistant-protocol`: the shapes and pure rules the
+ * assistant's browser and server share (analytics agent Plan 1, spec 2).
+ * Defined once here and imported by semaphor-app; nothing is copied.
+ */
+export * from './request.js';
+export { assistantJsonBytes, fitAssistantText, AssistantContextTooLargeError, } from './limits.js';
+export * from './context.js';
+export * from './availability.js';
+export * from './parts.js';
+export * from './conversation.js';
+export * from './transcript.js';
+export * from './sources.js';
+export * from './token-config.js';
+export * from './artifact.js';
+export * from './add-to-dashboard.js';

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

@@ -0,0 +1,53 @@
+/**
+ * Every cap of the assistant's request and context, in one place (analytics
+ * agent Plan 1, spec 2.1, ledger D3a-7). The server's schema and the browser's
+ * projection read these. Past a list cap the projection counts what it left
+ * out (`omitted`); past a text cap it says so in the text. Nothing is cut
+ * silently.
+ */
+export declare const ASSISTANT_LIMITS: {
+    readonly messageChars: 4000;
+    /** The whole serialized AssistantContext, in UTF-8 bytes. */
+    readonly contextBytes: number;
+    /** The whole request body (context, message, added sources), in UTF-8 bytes. */
+    readonly requestBytes: number;
+    readonly summaryCards: 30;
+    readonly otherSheets: 50;
+    readonly activeInputs: 50;
+    /** Values listed for one input, or in one filter's text. */
+    readonly inputValues: 50;
+    readonly addedSources: 50;
+    readonly cardFields: 60;
+    readonly cardFilters: 40;
+    readonly cardControls: 40;
+    readonly drillSteps: 10;
+    readonly sqlChars: 20000;
+    readonly sqlParameters: 40;
+    readonly idChars: 200;
+    readonly labelChars: 500;
+    /** One filter, control or SQL parameter description. */
+    readonly textChars: 4000;
+    readonly turnsPerConversation: 40;
+    readonly conversationBytes: number;
+    readonly toolCallsPerTurn: 12;
+    readonly secondsPerTurn: 120;
+    readonly artifactRecords: 200;
+    readonly conversationTtlSeconds: number;
+};
+/** UTF-8 bytes of a value's JSON, the measure both the browser and the server use. */
+export declare function assistantJsonBytes(value: unknown): number;
+/**
+ * Text within `max` characters. Longer text keeps its start and says how much
+ * was left out, so a reader never takes a cut text for the whole.
+ */
+export declare function fitAssistantText(text: string, max: number): string;
+/**
+ * The context the browser built is larger than `contextBytes`: nothing is
+ * sent, and the draft stays where it is. The server answers the same case
+ * with the `context_too_large` refusal.
+ */
+export declare class AssistantContextTooLargeError extends Error {
+    readonly bytes: number;
+    readonly code: "context_too_large";
+    constructor(bytes: number);
+}

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

@@ -0,0 +1,140 @@
+import { SemaphorDialect, SemaphorSourceRef } from '../analytics-protocol/contracts.js';
+import { AssistantArtifact } from './artifact.js';
+/**
+ * The parts of an answer (analytics agent Plan 1, spec 2.4). Streamed as AI
+ * SDK `data-${kind}` parts (text uses the SDK's own text parts) and stored on
+ * the turn as they are. Never a card config (AG-INV-5). Artifacts from
+ * Phase 4; proposals in Phase 7.
+ */
+export declare const ASSISTANT_PARTS_VERSION: 1;
+export type AssistantPart = {
+    kind: 'conversation';
+    conversationId: string;
+    expiresAt: string;
+} | {
+    kind: 'text';
+    text: string;
+} | AssistantStagePart | {
+    kind: 'using';
+    items: AssistantUsingItem[];
+    notes: string[];
+} | AssistantClarifyPart | {
+    kind: 'artifact';
+    artifact: AssistantArtifact;
+} | {
+    kind: 'refusal';
+    code: AssistantRefusalCode;
+    message: string;
+} | AssistantTracePart;
+/**
+ * A question the person answers with a click, ending the answer (ledger
+ * D3d-1): the model's alternatives as data, never parsed from its text. Each
+ * option is a complete request the assistant can run as written, so a pick is
+ * sent as the person's next message, words unchanged. Only the latest
+ * answer's options can be picked.
+ */
+export type AssistantClarifyPart = {
+    kind: 'clarify';
+    question: string;
+    options: Array<{
+        optionId: string;
+        label: string;
+        description?: string;
+    }>;
+};
+export type AssistantStagePart = {
+    kind: 'stage';
+    stageId: string;
+    label: string;
+    state: 'live' | 'done' | 'skipped';
+};
+/**
+ * Where one answer's time and tokens went (spec 3.9, AG-D25). The server
+ * sends it only to people who may see it (a development server, a super
+ * admin); the transcript shows it inside the answer's steps. Times are
+ * milliseconds from the message arriving.
+ */
+export type AssistantTracePart = {
+    kind: 'trace';
+    totalMs: number;
+    /** `provider/modelId`, as the turn's log line names it. */
+    model: string;
+    instructionsVersion: string;
+    tokens: AssistantTraceTokens;
+    /** In the order they started. */
+    spans: AssistantTraceSpan[];
+};
+export type AssistantTraceTokens = {
+    input: number;
+    cachedInput: number;
+    output: number;
+};
+export type AssistantTraceSpan = {
+    kind: 'check';
+    label: string;
+    startMs: number;
+    durationMs: number;
+} | {
+    kind: 'model';
+    startMs: number;
+    durationMs: number;
+    /** Until the model's first output. */
+    firstOutputMs?: number;
+    tokens: AssistantTraceTokens;
+}
+/** A step: its words are the stage part with this id. */
+ | {
+    kind: 'step';
+    stageId: string;
+    startMs: number;
+    durationMs: number;
+};
+/** What an answer used, shown as chips at its top. `notes` carry caveats ("Region is not applied: this card does not use it"). */
+export type AssistantUsingItem = {
+    kind: 'card';
+    cardId: string;
+    title: string;
+    change?: string;
+} | {
+    kind: 'draft';
+    title: string;
+} | {
+    kind: 'source';
+    source: SemaphorSourceRef;
+    added: boolean;
+} | {
+    kind: 'sql';
+    connectionLabel: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'input';
+    label: string;
+    value: string;
+} | {
+    kind: 'period';
+    label: string;
+    from: string;
+    to: string;
+};
+export type AssistantRefusalCode = 'assistant_unavailable' | 'context_invalid' | 'context_too_large' | 'conversation_not_found' | 'conversation_full' | 'turn_in_progress' | 'daily_limit_reached' | 'budget_exhausted' | 'not_permitted' | 'no_data_found' | 'model_unavailable';
+/**
+ * The data parts of the AI SDK UI message stream, by name: `data-${kind}`
+ * with the part (minus `kind`) as its data. Text is the SDK's own part. For
+ * `UIMessage<unknown, AssistantDataParts>` in the browser.
+ */
+export type AssistantDataParts = {
+    [Kind in Exclude<AssistantPart['kind'], 'text'>]: Omit<Extract<AssistantPart, {
+        kind: Kind;
+    }>, 'kind'>;
+};
+/**
+ * The words past the daily question limit (spec 3.8, AG-D24), with the
+ * deployment's limit when the refusal carried it.
+ */
+export declare function dailyLimitMessage(limit?: number): string;
+/** What a refusal says: its code's words, with the details the server sent for that code. */
+export declare function assistantRefusalMessage(code: AssistantRefusalCode, details?: {
+    dailyLimit?: number;
+}): string;
+/** Plain words for each refusal; never a tool name and never the product name (AG-INV-10). */
+export declare const ASSISTANT_REFUSAL_MESSAGES: Record<AssistantRefusalCode, string>;

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

@@ -0,0 +1,77 @@
+import { SemaphorSourceRef } from '../analytics-protocol/contracts.js';
+import { CardQueryRequestExtras, DashboardCardQueryRequestPayloadBase } from '../dashboard-authoring/card-query-request.js';
+import { DataSource } from '../../lib/types/explorer-types.js';
+import { AssistantContext } from './context.js';
+export { ASSISTANT_LIMITS } from './limits.js';
+/**
+ * The assistant's turn request (analytics agent Plan 1, spec 2.1). The browser
+ * sends one new message and the context; never history.
+ */
+/** Body of POST /api/v1/assistant/turns. One new message; never history. */
+export type AssistantTurnRequest = {
+    /** Idempotency key, new per send (`crypto.randomUUID()`); a retry reuses it. */
+    turnId: string;
+    /** Omitted to start a conversation; the stream's first part carries the new id. */
+    conversationId?: string;
+    /** Plain text, 1 to ASSISTANT_LIMITS.messageChars characters. */
+    message: string;
+    /** What the user is looking at (spec 2.2). */
+    context: AssistantContext;
+    /** Sources added with Add source (spec 2.7). Kept on the conversation until removed. */
+    addedSources: SemaphorSourceRef[];
+    /**
+     * The asked-about card's request, as the card posts it to /api/v1/query
+     * (Phase 3b, D3b-2): the server replays it with `fromCard`. Outside the
+     * context, so the model's text and change detection never read it.
+     */
+    selectedCardRequest?: AssistantCardRequest;
+    /**
+     * Why the asked-about card has no request (ledger P3-92). With a selected
+     * card the browser sends exactly one of `selectedCardRequest` and this, so
+     * the server never works out from a missing request which card was asked
+     * about or why it cannot run.
+     */
+    selectedCardUnavailable?: AssistantCardUnavailable;
+};
+/**
+ * Why a card has no request to replay: the reasons the external path's saved
+ * card refuses with (`buildSavedCardRequest`), and `pending` (the browser has
+ * not built the card's snapshot yet).
+ */
+export declare const ASSISTANT_CARD_UNAVAILABLE_REASONS: readonly ["matrix", "no_query", "document_section", "blocked", "pending"];
+export type AssistantCardUnavailableReason = (typeof ASSISTANT_CARD_UNAVAILABLE_REASONS)[number];
+export type AssistantCardUnavailable = {
+    cardId: string;
+    reason: AssistantCardUnavailableReason;
+    /** The card's own words, for a blocked filter mapping. */
+    message?: string;
+};
+/** A card's request for a server replay: its connection and the payload the card query assembly builds. */
+export type AssistantCardRequest = {
+    cardId: string;
+    connectionId: string;
+    /**
+     * The card query assembly's request with its extras (the first page of a
+     * server-paginated table, table totals) and the card's data source
+     * (`buildCardServerRequest`); the server checks it with the shared
+     * `parseCardQueryRequest` and `parseCardQueryRequestExtras` before it runs.
+     */
+    payload: DashboardCardQueryRequestPayloadBase & CardQueryRequestExtras & {
+        cardDataSource: DataSource;
+    };
+};
+export type AssistantTurnRequestParseResult = {
+    ok: true;
+    value: AssistantTurnRequest;
+} | {
+    ok: false;
+    code: 'context_too_large' | 'context_invalid';
+    issues: string[];
+};
+/**
+ * Parses a turn request body as received (text). Size first, before any
+ * parsing: a body over `requestBytes` or a context over `contextBytes` is
+ * `context_too_large`. Then the schema (strict) and the context version: a
+ * failure is `context_invalid`.
+ */
+export declare function parseAssistantTurnRequest(bodyText: string): AssistantTurnRequestParseResult;

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

@@ -0,0 +1,27 @@
+import { SemaphorSourceRef } from '../analytics-protocol/contracts.js';
+/**
+ * Adding a source to a conversation (analytics agent Plan 1, spec 2.7,
+ * D3c-10). The server's `listAddableSources` is the one owner of what a
+ * caller may add; the menu shows it and every turn is checked against it.
+ */
+export type AddableSourceGroup = 'semantic_datasets' | 'connections';
+export type AddableSource = {
+    /** A semantic dataset (`kind: 'semantic'`), or a connection for its direct tables (`kind: 'sql'`). */
+    source: SemaphorSourceRef;
+    label: string;
+    /** For a semantic dataset: its domain's label, which the menu groups by. */
+    domainLabel?: string;
+    group: AddableSourceGroup;
+};
+/** Body of `GET /api/v1/assistant/sources`. */
+export type AddableSourcesResponse = {
+    sources: AddableSource[];
+};
+/**
+ * Which source a reference names, for comparing an added source with the
+ * catalog: a dataset by its domain and name, a connection by its id. Labels
+ * and optional ids never decide. Undefined for a kind that cannot be added.
+ */
+export declare function addableSourceKey(source: SemaphorSourceRef): string | undefined;
+/** A source's name for the viewer: its label, else what it names. */
+export declare function sourceRefLabel(source: SemaphorSourceRef): string;

package/dist/types/shared/assistant-protocol/token-config.d.ts

@@ -0,0 +1,32 @@
+import { AssistantLayout } from './conversation.js';
+/**
+ * The assistant's token options (analytics agent Plan 1, spec 4, Phase 6):
+ * `config.assistant` on a token request. One owner for reading them (the
+ * server's availability and name, the browser's availability, name and
+ * layout) and for validating them (the token route). The deleted assistant's
+ * flat `showDashboardAssistant`, which customers still send, stands in for
+ * `enabled` when `enabled` is absent.
+ */
+export type AssistantTokenConfig = {
+    /** Shows the assistant on this token. The project's switches can still turn it off; a user identity is required. */
+    enabled?: boolean;
+    /** The assistant's name in what viewers read; 1 to 40 characters. Default "Assistant". */
+    name?: string;
+    /** The layout before the viewer chooses one. Default 'docked-right'. */
+    layout?: AssistantLayout;
+};
+export type ResolvedAssistantTokenConfig = {
+    enabled: boolean | undefined;
+    name: string;
+    layout: AssistantLayout | undefined;
+};
+/** A token's assistant options, as every reader uses them. Anything malformed reads as absent. */
+export declare function readAssistantTokenConfig(config: unknown): ResolvedAssistantTokenConfig;
+/** For the token route: `config.assistant` checked and its name trimmed, or the issues in plain words. */
+export declare function parseAssistantTokenConfig(value: unknown): {
+    ok: true;
+    value: AssistantTokenConfig;
+} | {
+    ok: false;
+    issues: string[];
+};

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

@@ -0,0 +1,40 @@
+import { AssistantDataParts, AssistantPart } from './parts.js';
+import { TurnOutcome } from './conversation.js';
+/**
+ * One mapping from a stored part to what the transcript shows (analytics
+ * agent Plan 1, Phase 3c, D3c-6). The turn's stream writes these, live and
+ * when a retried turn is answered again, and opening a stored conversation
+ * shows them, so history reads exactly as it streamed. A data part is the
+ * same object as a stream chunk and as a message part (AI SDK
+ * `data-${kind}`); text is one message part and three chunks on the wire.
+ */
+export type AssistantTranscriptDataPart = {
+    [Kind in keyof AssistantDataParts]: {
+        type: `data-${Kind}`;
+        /** A stage's id: later states replace the earlier one. */
+        id?: string;
+        data: AssistantDataParts[Kind];
+    };
+}[keyof AssistantDataParts];
+export type AssistantTranscriptPart = {
+    type: 'text';
+    text: string;
+} | AssistantTranscriptDataPart;
+export type AssistantTranscriptChunk = AssistantTranscriptDataPart | {
+    type: 'text-start' | 'text-end';
+    id: string;
+} | {
+    type: 'text-delta';
+    id: string;
+    delta: string;
+};
+export declare function toTranscriptPart(part: AssistantPart): AssistantTranscriptPart;
+/** A stored part as stream chunks; `textId` names a text part's chunks. */
+export declare function toTranscriptChunks(part: AssistantPart, textId: string): AssistantTranscriptChunk[];
+/**
+ * How history shows a turn that did not end with its answer: the words its
+ * stream ended with. A failed or interrupted turn ends with "could not
+ * answer" (its stream ended with that error); a turn still running says so.
+ * Other turns end with their own parts.
+ */
+export declare function storedTurnEnding(outcome: TurnOutcome): AssistantPart | undefined;

package/dist/types/shared/dashboard-authoring/card-query-request.d.ts

@@ -0,0 +1,112 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { ControlBinding, ControlDefinition, TCard, TDashboard } from '../../lib/types/common-types.js';
+import { CardConfig, DataSource, TableTotalsRequest } from '../../lib/types/explorer-types.js';
+import { TableConfig } from '../../lib/types/query-types.js';
+import { ResolvedPrimaryDateField } from '../analytics-protocol/contracts.js';
+import { GlobalDateComparisonContext } from '../analytics-protocol/metric-comparison.js';
+import { CalendarContext } from '../report-runtime-context/report-runtime-context.js';
+import { TemporalResultOwner } from './temporal-result-owner.js';
+/**
+ * A card's query request: what the card posts to `/api/v1/query`, and what
+ * the server reads back. One owner for both sides (analytics agent Plan 1,
+ * ledger P3-78): the card query assembly builds `DashboardCardQueryRequestPayloadBase`,
+ * `buildCardServerRequest` adds the connection and data source, and every
+ * server reader (the query route, CSV export, a stored export's run, the
+ * analytics agent's card replay) checks it with `parseCardQueryRequest` or,
+ * for a body that may not be a card's, `parseCardQueryRequestContext`.
+ */
+/** The request the card query assembly builds for one card. */
+export type DashboardCardQueryRequestPayloadBase = {
+    cardId: string;
+    sql: string;
+    python: string;
+    resultOwner: TemporalResultOwner;
+    active_filters: TFilterValue[];
+    controlValues: Record<string, unknown>;
+    controlDefinitions: ControlDefinition[];
+    cardControlDefinitions: ControlDefinition[];
+    controlBindings: ControlBinding[];
+    cache_config: TDashboard['globalCacheConfig'];
+    queryConfig: TCard['queryConfig'];
+    tableConfig: TableConfig;
+    cardType: TCard['type'];
+    cardTitle: string;
+    cardConfig: CardConfig;
+    cardDataSource: TCard['dataSource'];
+    resolvedPrimaryDateField?: ResolvedPrimaryDateField;
+    globalDateComparison?: GlobalDateComparisonContext;
+    calendarContext: CalendarContext;
+};
+/** The fields the server runs a card with. */
+export declare const CARD_QUERY_REQUEST_EXECUTED_FIELDS: readonly ["cardType", "sql", "python", "resultOwner", "cardConfig", "cardDataSource", "active_filters", "controlValues", "controlDefinitions", "cardControlDefinitions", "controlBindings", "resolvedPrimaryDateField", "globalDateComparison", "calendarContext"];
+/**
+ * The fields that describe the card for its own view and logs; the server
+ * does not run with them (the result cache `cache_config` names is off).
+ */
+export declare const CARD_QUERY_REQUEST_DESCRIPTIVE_FIELDS: readonly ["cardId", "cardTitle", "cache_config", "queryConfig", "tableConfig"];
+type DecidedField = (typeof CARD_QUERY_REQUEST_EXECUTED_FIELDS)[number] | (typeof CARD_QUERY_REQUEST_DESCRIPTIVE_FIELDS)[number];
+type AssertNever<T extends never> = T;
+/**
+ * Every field the assembly builds is decided: run or descriptive. A new field
+ * fails the type check here until the parser reads it or it is listed as
+ * descriptive, so a reader never drops it silently.
+ */
+export type CardQueryRequestFieldsDecided = AssertNever<Exclude<keyof DashboardCardQueryRequestPayloadBase, DecidedField>>;
+/** A card's request as the server runs it. */
+export type CardQueryRequest = Omit<Pick<DashboardCardQueryRequestPayloadBase, (typeof CARD_QUERY_REQUEST_EXECUTED_FIELDS)[number]>, 'calendarContext' | 'cardDataSource'> & {
+    connection_id: string;
+    cardDataSource: DataSource;
+    /** Absent when the caller runs with a calendar of its own (a CSV export's report context). */
+    calendarContext?: CalendarContext;
+};
+/**
+ * What a card's query runs with beyond the assembly's request: the page a
+ * server-paginated table runs, and a flat table's totals request. Built by
+ * `resolveCardRequestExtras` for the live query and a captured request alike.
+ */
+export type CardQueryRequestExtras = {
+    pagination?: {
+        page: number;
+        pageSize: number;
+    };
+    tableTotalsRequest?: TableTotalsRequest;
+};
+/** The context fields any query body may carry, checked the same way for every reader. */
+export type CardQueryRequestContext = Pick<CardQueryRequest, 'calendarContext' | 'resolvedPrimaryDateField' | 'globalDateComparison'>;
+/**
+ * A request a reader refuses: `message` names the first problem; `details`
+ * carries the field validator's own issues, for readers that answer with them.
+ */
+export declare class CardQueryRequestError extends Error {
+    readonly field: string;
+    readonly details: unknown;
+    constructor(message: string, field: string, details?: unknown);
+}
+type ReadOptions = {
+    /** Prefixes every message, as a stored rule's reader names where the request sits. */
+    label?: string;
+};
+/**
+ * The context fields of any query body: the calendar, the resolved primary
+ * date field and the dashboard date comparison (without the legacy clock; an
+ * execution pins its own instant). Throws `CardQueryRequestError`.
+ */
+export declare function parseCardQueryRequestContext(input: unknown, options?: ReadOptions): CardQueryRequestContext;
+/**
+ * The extras of a card's request (`CardQueryRequestExtras`). The totals
+ * request is checked where it runs (`executeQuery`), as for every query.
+ * Throws `CardQueryRequestError`.
+ */
+export declare function parseCardQueryRequestExtras(input: unknown, options?: ReadOptions): CardQueryRequestExtras;
+/**
+ * A card's request, checked before it runs: connection, card type, the result
+ * owner (which of config, SQL or Python owns the rows), the config and data
+ * source, filters, the control contract and the context fields. Throws
+ * `CardQueryRequestError` (controls: `ExecutionControlContractError`) with the
+ * first problem. Callers add only their own rules.
+ */
+export declare function parseCardQueryRequest(input: unknown, options?: ReadOptions & {
+    /** A Matrix export continuation carries its configuration in its acquisition. */
+    configOptional?: boolean;
+}): CardQueryRequest;
+export {};