@bbigbang/protocol 0.1.0

package/dist/panel.d.ts

@@ -0,0 +1,823 @@
+export type Panel = {
+    id: string;
+    agentId: string;
+    conversationId: string;
+    ownerUserId?: string;
+    handle?: string | null;
+    scopeType: 'direct' | 'channel' | 'thread' | 'tool';
+    scopeId?: string;
+    toolId?: string;
+    surfaceProfile?: PanelSurfaceProfile;
+    surfaceFeatures?: PanelSurfaceFeatures;
+    component: string;
+    props?: Record<string, unknown>;
+    actions?: PanelAction[];
+    rowCount?: number;
+    rowCountKnown?: boolean;
+    datasetSource?: PanelDatasetSource;
+    status: PanelStatus;
+    progress?: Record<string, unknown> | null;
+    result?: Record<string, unknown> | null;
+    version: number;
+    createdByRunId?: string;
+    createdAt: string;
+    updatedAt: string;
+    archivedAt?: string | null;
+};
+export type PanelSurfaceProfile = 'panel' | 'tool';
+export type PanelSurfaceFeatures = {
+    browseControls?: boolean;
+};
+export type PanelRow = {
+    panelId: string;
+    rowIndex: number;
+    rowId?: string | null;
+    fields: Record<string, unknown>;
+    media: Record<string, {
+        kind: 'workspace_path' | 'asset';
+        value: string;
+    }>;
+    nodeId?: string;
+    cachedAssetIds?: Record<string, string>;
+};
+export type PanelState = {
+    panelId: string;
+    userId: string;
+    state: Record<string, unknown>;
+    updatedAt: string;
+};
+export type PanelActionMode = 'notify_agent' | 'platform_exec';
+export type PanelActionToolKind = 'start' | 'stop' | 'status' | 'restart' | 'custom';
+export type PanelActionParamInput = 'text' | 'number' | 'checkbox' | 'select';
+export type PanelActionParamField = {
+    name: string;
+    label?: string;
+    description?: string;
+    input?: PanelActionParamInput;
+    required?: boolean;
+    placeholder?: string;
+    defaultValue?: unknown;
+    min?: number;
+    max?: number;
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+};
+export type PanelAction = {
+    id: string;
+    label: string;
+    mode?: PanelActionMode;
+    /**
+     * Promotion hint for panel-to-tool upgrades. Ignored by ordinary panel action execution.
+     * When present, direct promotion maps this to the Workspace Tool action kind.
+     */
+    toolKind?: PanelActionToolKind;
+    variant?: 'primary' | 'secondary' | 'danger';
+    description?: string;
+    command?: string;
+    cwd?: string;
+    /** Promotion hint copied to Workspace Tool action manifests. */
+    persistent?: boolean;
+    /** Promotion hint copied to persistent Workspace Tool start/restart actions. */
+    maxRunSeconds?: number;
+    /** Promotion hint copied to persistent Workspace Tool start/restart actions. */
+    idleTimeoutSeconds?: number;
+    /** Promotion hint copied to Workspace Tool action manifests. Not used by ordinary panel action execution. */
+    paramsSchema?: PanelActionParamField[];
+    /** @deprecated Use command. Retained for legacy stored panels. */
+    rpcCommand?: string;
+    /** @deprecated Use cwd. Retained for legacy stored panels. */
+    rpcCwd?: string;
+};
+export type PanelBadgeValueMapEntry = {
+    value: string | number | boolean | null;
+    label?: string;
+    variant?: 'default' | 'success' | 'warning' | 'danger';
+};
+export type PanelFormFieldOption = {
+    value: string | number | boolean;
+    label?: string;
+};
+export type PanelUploadedFileRef = {
+    assetId: string;
+    attachmentId?: string;
+    filename: string;
+    sizeBytes: number;
+    kind?: string;
+    scopeType?: string;
+    scopeId?: string;
+};
+export declare const DEFAULT_PANEL_PAGE_SIZE = 10;
+export declare const MIN_PANEL_PAGE_SIZE = 1;
+export declare const MAX_PANEL_PAGE_SIZE = 50;
+export declare const MIN_PANEL_REFRESH_INTERVAL_MS = 1000;
+export declare const MAX_PANEL_REFRESH_INTERVAL_MS = 60000;
+export type ImageReviewGridProps = {
+    title?: string;
+    showScore?: boolean;
+    pageSize?: number;
+    refreshIntervalMs?: number;
+};
+export type PanelStatus = 'idle' | 'running' | 'completed' | 'failed';
+export type PanelInputRow = {
+    rowId?: string;
+    fields: Record<string, unknown>;
+    media?: Record<string, {
+        kind: 'workspace_path' | 'asset';
+        value: string;
+    }>;
+};
+export type PanelPatchInput = {
+    panelId: string;
+    expectedVersion?: number;
+    props_patch?: Record<string, unknown>;
+    actions?: PanelAction[];
+    rows?: {
+        append?: PanelInputRow[];
+        upsert?: PanelInputRow[];
+        remove_row_ids?: string[];
+    };
+    status?: PanelStatus;
+    progress?: Record<string, unknown> | null;
+    result?: Record<string, unknown> | null;
+};
+export declare const INLINE_ROWS_MAX = 1000;
+export type PanelApiJsonlDatasetSource = {
+    kind: 'api_jsonl';
+    url: string;
+    urls?: never;
+    auth?: PanelApiJsonlAuthProfile;
+} | {
+    kind: 'api_jsonl';
+    urls: string[];
+    url?: never;
+    auth?: PanelApiJsonlAuthProfile;
+};
+export type PanelApiJsonlAuthProfile = {
+    profile: string;
+};
+export type PanelDatasetSource = {
+    kind: 'workspace_jsonl';
+    path: string;
+} | {
+    kind: 'inline_rows';
+    rows: PanelInputRow[];
+} | {
+    kind: 'attachment_manifest';
+    attachmentId?: string;
+    assetId?: string;
+} | {
+    kind: 'query_handle';
+    handle: string;
+} | PanelApiJsonlDatasetSource;
+export declare const PANEL_API_JSONL_MAX_URLS = 16;
+export declare const PANEL_MEDIA_FETCH_CONCURRENCY = 6;
+export declare const PANEL_MEDIA_REMOTE_FETCH_TIMEOUT_MS = 10000;
+export declare const PANEL_IMAGE_MEDIA_MAX_BYTES: number;
+export declare const PANEL_TEXT_MEDIA_MAX_BYTES: number;
+export type PanelApiJsonlUrlValidationResult = {
+    ok: true;
+    url: string;
+    origin: string;
+    defaultLoopback: boolean;
+    matchedAllowedPrefix: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export type PanelApiJsonlUrlListValidationResult = {
+    ok: true;
+    urls: string[];
+    authProfile: string | null;
+} | {
+    ok: false;
+    reason: string;
+    missingField?: string;
+};
+export declare function normalizePanelApiJsonlAuthProfileName(rawProfile: string): string | null;
+export declare function normalizePanelApiJsonlAuthProfileNames(rawProfiles: string | readonly string[] | null | undefined): string[];
+export declare function validatePanelApiJsonlAuthProfile(rawAuth: unknown, options?: {
+    allowedAuthProfiles?: readonly string[];
+}): {
+    ok: true;
+    authProfile: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function normalizePanelApiJsonlAllowedOrigin(rawOrigin: string): string | null;
+export declare function normalizePanelApiJsonlAllowedOrigins(rawOrigins: string | readonly string[] | null | undefined): string[];
+export declare function normalizePanelApiJsonlAllowedUrlPrefix(rawPrefix: string): string | null;
+export declare function normalizePanelApiJsonlAllowedUrlPrefixes(rawPrefixes: string | readonly string[] | null | undefined): string[];
+export declare function matchPanelApiJsonlAllowedUrlPrefix(parsed: URL, rawPrefixes: string | readonly string[] | null | undefined): string | null;
+export declare function isPanelApiJsonlDefaultLoopbackUrl(parsed: URL): boolean;
+export declare function validatePanelApiJsonlUrl(rawUrl: string, options?: {
+    allowedOrigins?: readonly string[];
+    allowedUrlPrefixes?: readonly string[];
+}): PanelApiJsonlUrlValidationResult;
+export declare function validatePanelApiJsonlUrlList(source: {
+    url?: unknown;
+    urls?: unknown;
+}, options?: {
+    allowedOrigins?: readonly string[];
+    allowedUrlPrefixes?: readonly string[];
+    allowedAuthProfiles?: readonly string[];
+}): PanelApiJsonlUrlListValidationResult;
+export type PanelDatasetInput = {
+    source: PanelDatasetSource;
+    rows?: never;
+} | {
+    rows: string;
+    source?: never;
+};
+export type PanelSubmitKind = 'action' | 'form' | 'apply' | 'done';
+export type PanelSubmitScope = {
+    type: 'direct';
+    conversationId: string;
+} | {
+    type: 'channel';
+    conversationId: string;
+    channelId: string;
+} | {
+    type: 'thread';
+    conversationId: string;
+    channelId: string;
+    threadRootId: string;
+};
+type PanelSubmitPayloadBase = {
+    panelId: string;
+    actor: {
+        userId: string;
+        username: string;
+    };
+    scope: PanelSubmitScope;
+    baseVersion: number;
+    submittedVersion: number;
+    concurrency?: {
+        staleBase: boolean;
+        latestVersion?: number;
+    };
+    viewState: {
+        filters?: Record<string, unknown>;
+        sort?: Record<string, unknown>;
+        activeTab?: string;
+    };
+    refs: {
+        selectedRowIndices?: number[];
+        selectedRowIds?: string[];
+        changedRowIndices?: number[];
+        changedRowIds?: string[];
+    };
+    delta: {
+        shared?: Record<string, unknown>;
+        perUser?: Record<string, unknown>;
+        form?: Record<string, {
+            from?: unknown;
+            to: unknown;
+        }>;
+    };
+    summary: {
+        selectedCount?: number;
+        changedFieldCount?: number;
+        truncated?: boolean;
+    };
+    preview?: {
+        rows?: Array<{
+            rowIndex: number;
+            fields: Record<string, unknown>;
+        }>;
+    };
+    metadata?: Record<string, unknown>;
+};
+export type PanelSubmitPayload = (PanelSubmitPayloadBase & {
+    submitKind: 'action';
+    actionId: string;
+}) | (PanelSubmitPayloadBase & {
+    submitKind: Exclude<PanelSubmitKind, 'action'>;
+    actionId?: never;
+});
+export type DataModelKind = 'inline' | 'paged_rows';
+export type DatasetFieldSchema = {
+    name: string;
+    label?: string;
+    type: 'string' | 'number' | 'boolean';
+    filterable?: boolean;
+    sortable?: boolean;
+};
+export type DatasetMediaSlotSchema = {
+    name: string;
+    kind: 'workspace_path' | 'asset';
+    displayType: 'img' | 'latex' | 'text';
+};
+export type DatasetSchema = {
+    fields: DatasetFieldSchema[];
+    mediaSlots: DatasetMediaSlotSchema[];
+};
+export type PanelTemplateGap = 'none' | 'sm' | 'md' | 'lg';
+export type PanelVisibilityCondition = {
+    field: string;
+    op?: 'exists' | 'not_empty' | 'equals' | 'not_equals' | 'in' | 'not_in' | 'contains' | 'truthy' | 'falsy';
+    value?: unknown;
+    values?: unknown[];
+};
+export type PanelKeyValueTone = 'default' | 'success' | 'warning' | 'danger';
+export type PanelKeyValueItem = {
+    label: string;
+    field?: string;
+    source?: string;
+    value?: unknown;
+    fallback?: string;
+    tone?: PanelKeyValueTone;
+};
+export type PanelTemplateNode = ({
+    type: 'Row' | 'Column';
+    children: PanelTemplateNode[];
+    gap?: PanelTemplateGap;
+    align?: 'start' | 'center' | 'end' | 'stretch';
+} | {
+    type: 'Card';
+    children: PanelTemplateNode[];
+    title?: string;
+    titleField?: string;
+} | {
+    type: 'Tabs';
+    items: Array<{
+        label: string;
+        node: PanelTemplateNode;
+    }>;
+    defaultIndex?: number;
+} | {
+    type: 'Stack';
+    children: PanelTemplateNode[];
+    direction?: 'vertical' | 'horizontal';
+    gap?: PanelTemplateGap;
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    wrap?: boolean;
+} | {
+    type: 'Inline';
+    children: PanelTemplateNode[];
+    gap?: PanelTemplateGap;
+    align?: 'start' | 'center' | 'end';
+    wrap?: boolean;
+} | {
+    type: 'Grid';
+    children: PanelTemplateNode[];
+    minColumnWidth?: number;
+    maxColumns?: number;
+    gap?: Exclude<PanelTemplateGap, 'none'>;
+} | {
+    type: 'KeyValueList';
+    items: PanelKeyValueItem[];
+} | {
+    type: 'TextField';
+    field: string;
+    label?: string;
+    fallback?: string;
+} | {
+    type: 'LatexBlock';
+    field: string;
+    fallback?: string;
+} | {
+    type: 'MarkdownField';
+    field: string;
+    fallback?: string;
+} | {
+    type: 'CodeField';
+    field: string;
+    language?: string;
+    languageField?: string;
+    fallback?: string;
+} | {
+    type: 'JsonField';
+    field: string;
+    expanded?: boolean;
+    fallback?: string;
+} | {
+    type: 'DiffField';
+    leftField: string;
+    rightField: string;
+    mode?: 'line' | 'char';
+    title?: string;
+} | {
+    type: 'Badge';
+    field: string;
+    label?: string;
+    variant?: 'default' | 'success' | 'warning' | 'danger';
+    valueMap?: PanelBadgeValueMapEntry[];
+    fallback?: string;
+} | {
+    type: 'ComputedValue';
+    op: 'sum' | 'difference' | 'product' | 'ratio' | 'percent' | 'average' | 'weighted_sum' | 'concat';
+    fields: string[];
+    weights?: number[];
+    label?: string;
+    precision?: number;
+    prefix?: string;
+    suffix?: string;
+    separator?: string;
+    fallback?: string;
+} | {
+    type: 'ImageSlot';
+    slot: string;
+    labelField?: string;
+    annotationsField?: string;
+    editable?: boolean;
+    newAnnotationLabel?: string;
+    shortcutLabels?: PanelAnnotationShortcut[];
+} | {
+    type: 'MediaBlock';
+    slot: string;
+    labelField?: string;
+    displayType?: 'img' | 'text' | 'latex';
+    maxLines?: number;
+    annotationsField?: string;
+    editable?: boolean;
+    newAnnotationLabel?: string;
+    shortcutLabels?: PanelAnnotationShortcut[];
+} | {
+    type: 'Checkbox';
+    label?: string;
+} | {
+    type: 'FormField';
+    name: string;
+    label?: string;
+    field?: string;
+    input?: 'text' | 'number' | 'checkbox' | 'textarea' | 'select' | 'tags';
+    placeholder?: string;
+    options?: PanelFormFieldOption[];
+} | {
+    type: 'ActionButton';
+    actionId: string;
+    label?: string;
+    help?: string;
+    showHelp?: boolean;
+} | {
+    type: 'SubmitButton';
+    submitKind: Exclude<PanelSubmitKind, 'action'>;
+    label?: string;
+    variant?: 'primary' | 'secondary' | 'danger';
+    help?: string;
+    showHelp?: boolean;
+} | {
+    type: 'Sparkline';
+    field: string;
+} | {
+    type: 'Accordion';
+    title: string;
+    children: PanelTemplateNode[];
+    expanded?: boolean;
+} | {
+    type: 'Divider';
+    title?: string;
+} | {
+    type: 'Callout';
+    calloutType: 'info' | 'warning' | 'success' | 'error';
+    title?: string;
+    content?: string;
+} | {
+    type: 'Columns';
+    columns: Array<{
+        width?: string;
+        children: PanelTemplateNode[];
+    }>;
+} | {
+    type: 'DiffView';
+    left: string;
+    right: string;
+    mode?: 'line' | 'char';
+} | {
+    type: 'CodeBlock';
+    code: string;
+    language?: string;
+} | {
+    type: 'JsonView';
+    data: unknown;
+    expanded?: boolean;
+} | {
+    type: 'MarkdownText';
+    content: string;
+}) & {
+    visibleWhen?: PanelVisibilityCondition;
+};
+export type PanelTemplateContainerNode = Extract<PanelTemplateNode, {
+    type: 'Row' | 'Column' | 'Card' | 'Tabs' | 'Accordion' | 'Columns' | 'Stack' | 'Inline' | 'Grid';
+}>;
+export type PanelTemplateNodeWalkContext = {
+    parent: PanelTemplateContainerNode | null;
+    depth: number;
+    index: number | null;
+    columnIndex?: number;
+    tabIndex?: number;
+};
+export type PanelTemplateNodeVisitor = (node: PanelTemplateNode, context: PanelTemplateNodeWalkContext) => void | false;
+export type PanelTemplateUnsupportedNodePolicy = {
+    unsupportedTypes?: ReadonlySet<string> | readonly string[];
+    interactiveTypes?: ReadonlySet<string> | readonly string[];
+    allowInteractiveTypes?: boolean;
+    predicate?: (node: PanelTemplateNode) => boolean;
+};
+export type PanelSummaryDataSource = {
+    kind: 'inline';
+    data: unknown;
+} | {
+    kind: 'panel_result';
+    path: string[];
+} | {
+    kind: 'panel_progress';
+    path: string[];
+};
+export type PanelAnnotation = {
+    label: string;
+    box: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    detail?: string;
+    color?: string;
+};
+export type PanelAnnotationShortcut = {
+    key: string;
+    label: string;
+    color?: string;
+};
+export type PanelLevelNode = {
+    type: 'Section';
+    children: PanelLevelNode[];
+} | {
+    type: 'ParameterFormSection';
+    children: PanelLevelNode[];
+} | {
+    type: 'Card';
+    children: PanelLevelNode[];
+    title?: string;
+} | {
+    type: 'Columns';
+    columns: Array<{
+        width?: string;
+        children: PanelLevelNode[];
+    }>;
+} | {
+    type: 'Stack';
+    children: PanelLevelNode[];
+    direction?: 'vertical' | 'horizontal';
+    gap?: PanelTemplateGap;
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    wrap?: boolean;
+} | {
+    type: 'Inline';
+    children: PanelLevelNode[];
+    gap?: PanelTemplateGap;
+    align?: 'start' | 'center' | 'end';
+    wrap?: boolean;
+} | {
+    type: 'Grid';
+    children: PanelLevelNode[];
+    minColumnWidth?: number;
+    maxColumns?: number;
+    gap?: Exclude<PanelTemplateGap, 'none'>;
+} | {
+    type: 'KeyValueList';
+    items: PanelKeyValueItem[];
+} | {
+    type: 'MetricCard';
+    props: Record<string, unknown>;
+} | {
+    type: 'AggregateValue';
+    op: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    scope?: 'page' | 'dataset';
+    field?: string;
+    label?: string;
+    precision?: number;
+    prefix?: string;
+    suffix?: string;
+    fallback?: string;
+} | {
+    type: 'BarChart' | 'LineChart' | 'PieChart' | 'Histogram';
+    props: Record<string, unknown>;
+} | {
+    type: 'ProgressBar' | 'StatusBadge' | 'Timeline';
+    source?: string;
+    label?: string;
+} | {
+    type: 'LogBlock';
+    source?: string;
+    title?: string;
+    maxLines?: number;
+    emptyText?: string;
+} | {
+    type: 'RunStatusCard';
+    run?: 'latest' | {
+        id: string;
+    };
+    showTarget?: boolean;
+    showRevision?: boolean;
+} | {
+    type: 'RunLogViewer';
+    run?: 'latest' | {
+        id: string;
+    };
+    maxLines?: number;
+    levels?: string[];
+    emptyText?: string;
+} | {
+    type: 'ArtifactList';
+    run?: 'latest' | {
+        id: string;
+    };
+    kinds?: string[];
+    emptyText?: string;
+} | {
+    type: 'TextInput' | 'TextArea' | 'NumberInput' | 'Checkbox' | 'Select' | 'MultiSelect' | 'TagInput' | 'Slider' | 'DatePicker' | 'FileUpload';
+    props: Record<string, unknown>;
+} | {
+    type: 'ActionBar';
+    actionIds?: string[];
+    layout?: 'wrap' | 'stack';
+    title?: string;
+    showDescriptions?: boolean;
+    showHelp?: boolean;
+} | {
+    type: 'Button';
+    props: Record<string, unknown>;
+};
+export type RowTemplateGridProps = {
+    title?: string;
+    pageSize?: number;
+    refreshIntervalMs?: number;
+    fields: DatasetFieldSchema[];
+    mediaSlots?: DatasetMediaSlotSchema[];
+    summary?: PanelLevelNode;
+    parameterForm?: PanelLevelNode;
+    template: PanelTemplateNode;
+};
+export type PanelLevelContainerNode = Extract<PanelLevelNode, {
+    type: 'Section' | 'ParameterFormSection' | 'Card' | 'Columns' | 'Stack' | 'Inline' | 'Grid';
+}>;
+export type PanelLevelActionBarNode = Extract<PanelLevelNode, {
+    type: 'ActionBar';
+}>;
+export type PanelLevelDatasetAggregateNode = Extract<PanelLevelNode, {
+    type: 'AggregateValue';
+}>;
+export type PanelLevelParameterInputNode = Extract<PanelLevelNode, {
+    type: 'TextInput' | 'TextArea' | 'NumberInput' | 'Checkbox' | 'Select' | 'MultiSelect' | 'TagInput' | 'Slider' | 'DatePicker' | 'FileUpload';
+}>;
+export type PanelLevelNodeWalkContext = {
+    parent: PanelLevelContainerNode | null;
+    depth: number;
+    index: number | null;
+    columnIndex?: number;
+};
+export type PanelLevelNodeVisitor = (node: PanelLevelNode, context: PanelLevelNodeWalkContext) => void | false;
+export type PanelLevelNodeMapper = (node: PanelLevelNode, context: PanelLevelNodeWalkContext) => PanelLevelNode | null | undefined;
+export type MapPanelLevelNodesOptions = {
+    pruneEmptyContainers?: boolean;
+    pruneEmptyColumns?: boolean;
+    collapseSingleChildContainers?: boolean;
+};
+export type PanelLevelUnsupportedNodePolicy = {
+    unsupportedTypes?: ReadonlySet<string> | readonly string[];
+    interactiveTypes?: ReadonlySet<string> | readonly string[];
+    allowInteractiveTypes?: boolean;
+    predicate?: (node: PanelLevelNode) => boolean;
+};
+export declare function isPanelTemplateContainerNode(node: PanelTemplateNode | null | undefined): node is PanelTemplateContainerNode;
+export declare function walkPanelTemplateNodes(node: PanelTemplateNode | null | undefined, visitor: PanelTemplateNodeVisitor): void;
+export declare function collectPanelTemplateUnsupportedNodes(node: PanelTemplateNode | null | undefined, policy?: PanelTemplateUnsupportedNodePolicy): PanelTemplateNode[];
+export declare function isPanelLevelContainerNode(node: PanelLevelNode | null | undefined): node is PanelLevelContainerNode;
+export declare function isPanelLevelActionBarNode(node: PanelLevelNode | null | undefined): node is PanelLevelActionBarNode;
+export declare function isPanelLevelParameterInputNode(node: PanelLevelNode | null | undefined): node is PanelLevelParameterInputNode;
+export declare function isPanelLevelDatasetAggregateNode(node: PanelLevelNode | null | undefined): node is PanelLevelDatasetAggregateNode;
+export declare function walkPanelLevelNodes(node: PanelLevelNode | null | undefined, visitor: PanelLevelNodeVisitor): void;
+export declare function mapPanelLevelNodes(node: PanelLevelNode | null | undefined, mapper: PanelLevelNodeMapper, options?: MapPanelLevelNodesOptions): PanelLevelNode | null;
+export declare function collectPanelLevelActionBars(node: PanelLevelNode | null | undefined): PanelLevelActionBarNode[];
+export declare function panelLevelNodeHasActionBar(node: PanelLevelNode | null | undefined): boolean;
+export declare function collectPanelLevelParameterInputs(node: PanelLevelNode | null | undefined): PanelLevelParameterInputNode[];
+export declare function collectDatasetAggregateNodes(node: PanelLevelNode | null | undefined): PanelLevelDatasetAggregateNode[];
+export declare function panelLevelNodeUsesDatasetAggregate(node: PanelLevelNode | null | undefined): boolean;
+export declare function panelLevelNodeContainsEmptyLayoutContainer(node: PanelLevelNode | null | undefined): boolean;
+export declare function isPanelLevelNodeEffectivelyEmpty(node: PanelLevelNode | null | undefined): boolean;
+export declare function collectPanelLevelUnsupportedNodes(node: PanelLevelNode | null | undefined, policy?: PanelLevelUnsupportedNodePolicy): PanelLevelNode[];
+export type ClientInteraction = 'filter' | 'sort' | 'select' | 'hover' | 'zoom' | 'edit' | 'autosave';
+export type SupportedActionSchema = {
+    id: string;
+    label: string;
+    description?: string;
+};
+export type ComponentContract = {
+    name: string;
+    displayName: string;
+    description: string;
+    dataModel: {
+        kind: DataModelKind;
+    };
+    propsSchema?: Record<string, unknown>;
+    datasetSchema?: DatasetSchema;
+    stateSchema?: Record<string, unknown>;
+    /** State keys that are shared across all users viewing this panel (e.g. selection). All other keys remain per-user. */
+    sharedStateKeys?: string[];
+    clientInteractions?: ClientInteraction[];
+    supportedActions?: SupportedActionSchema[];
+};
+export declare const COMPONENT_CONTRACTS: Record<string, ComponentContract>;
+export declare function getComponentContract(name: string): ComponentContract;
+export declare function listComponentContracts(): ComponentContract[];
+export declare function validatePanelLevelNode(node: unknown, options: {
+    path: string;
+    depth: number;
+    errors: string[];
+    slotName: string;
+    actionIds?: Set<string>;
+    fieldNames?: Set<string>;
+}): void;
+export declare function getEffectiveDatasetSchema(componentOrContract: string | ComponentContract, props?: Record<string, unknown>): DatasetSchema | undefined;
+export declare function validatePanelTemplateProps(componentOrContract: string | ComponentContract, props: Record<string, unknown>, actions?: Array<{
+    id: string;
+}>): {
+    ok: true;
+    datasetSchema: DatasetSchema;
+} | {
+    ok: false;
+    errors: string[];
+};
+export type PanelAuditEventType = 'created' | 'patched' | 'submitted' | 'actioned' | 'failed' | 'archived' | 'selection_committed' | 'annotation_saved' | 'state_saved';
+export type PanelAuditEvent = {
+    id: number;
+    panelId: string;
+    event: PanelAuditEventType;
+    timestamp: number;
+    version: number;
+    changed?: string[];
+    submitKind?: string;
+    actionId?: string;
+    failureClass?: string;
+    actorType: 'agent' | 'user' | 'system';
+    actorId: string | null;
+    runId: string | null;
+    conversationId: string;
+    scopeType: 'direct' | 'channel' | 'thread' | 'tool';
+    scopeId: string | null;
+    metadataJson: string;
+};
+export type PanelSemanticEventWakePolicy = 'persisted' | 'agent_visible';
+export type PanelSemanticEventRefs = {
+    selectedRowIndices?: number[];
+    selectedRowIds?: string[];
+    changedRowIndices?: number[];
+    changedRowIds?: string[];
+};
+export type PanelSemanticEvent = {
+    eventId: number;
+    panelId: string;
+    event: PanelAuditEventType;
+    label: string;
+    summary: string;
+    timestamp: number;
+    version: number;
+    wakePolicy: PanelSemanticEventWakePolicy;
+    changed?: string[];
+    submitKind?: string;
+    actionId?: string;
+    failureClass?: string;
+    actor: {
+        type: 'agent' | 'user' | 'system';
+        id: string | null;
+        runId: string | null;
+    };
+    conversationId: string;
+    scopeType: 'direct' | 'channel' | 'thread' | 'tool';
+    scopeId: string | null;
+    refs: PanelSemanticEventRefs;
+    metadataSummary: Record<string, unknown>;
+};
+export type ComponentProposalStatus = 'pending_review' | 'approved' | 'rejected';
+export type ComponentProposalInput = {
+    name: string;
+    displayName: string;
+    description: string;
+    dataModel: {
+        kind: DataModelKind;
+    };
+    propsSchema: Record<string, unknown>;
+    datasetSchema: DatasetSchema;
+    rationale: string;
+};
+export type ComponentProposal = ComponentProposalInput & {
+    id: string;
+    status: ComponentProposalStatus;
+    submittedAt: number;
+    reviewedAt?: number;
+};
+export declare function validateComponentProposal(input: unknown, existingContractNames: Set<string>): {
+    ok: true;
+} | {
+    ok: false;
+    errors: Array<{
+        field: string;
+        message: string;
+    }>;
+};
+export {};