@pgege/kaboo-react 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,8 +1,9 @@
 import { a as KabooInterruptHandlerProps, I as InterruptReason, A as ActivityState, D as DrillState, S as StreamGroup, T as ToolCall, b as InterruptRendererProps, c as TimelineEntry } from './KabooInterruptHandler-BO2Uv3gS.cjs';
 export { d as ApprovalReason, F as FormQuestion, e as FormReason, f as InterruptData } from './KabooInterruptHandler-BO2Uv3gS.cjs';
 import * as react from 'react';
-import { ReactElement, ReactNode } from 'react';
-import { CopilotKitProps } from '@copilotkit/react-core/v2';
+import { ReactElement, ReactNode, ComponentProps } from 'react';
+import { CopilotKitProps, CopilotChatInput } from '@copilotkit/react-core/v2';
+import { InputContent, AttachmentUploadResult, AttachmentsConfig } from '@copilotkit/shared';
 
 /**
  * A map of custom renderers for structured agent output, keyed by the output
@@ -79,6 +80,117 @@ declare function DrillProvider({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
 
+/**
+ * Wire keys shared with kaboo-workflows. A file attachment carries its id/kind/
+ * name in the CopilotKit `InputContent` part `metadata` under these keys; the
+ * Python side reads the same keys back out. Kept snake_case so both stacks
+ * agree without a translation layer.
+ */
+declare const REFERENCE_METADATA_KEYS: {
+    /** Metadata key carrying the reference id. */
+    readonly id: "kaboo_id";
+    /** Metadata key carrying the reference kind. */
+    readonly kind: "kaboo_kind";
+    /** Metadata key carrying the reference display name. */
+    readonly name: "kaboo_name";
+};
+/** AG-UI `state` key under which object-transport references travel. */
+declare const REFERENCES_STATE_KEY = "kaboo_references";
+/**
+ * How a reference reaches the agent.
+ *
+ * - `attachment` — a file/blob (pdf, image, csv, …). Serialized as a CopilotKit
+ *   `InputContent` part; its bytes are resolvable server-side. Files are the
+ *   only blob-capable transport.
+ * - `object` — a pointer to a custom entity (table, dashboard, ticket, …).
+ *   Serialized into `state.kaboo_references`; resolved by the app's own MCP
+ *   tool. Never carries bytes.
+ */
+type ReferenceTransport = "attachment" | "object";
+/**
+ * One selectable item surfaced by a {@link ReferenceProvider} in the `@` menu.
+ * `data` is provider-defined and threaded back to {@link ReferenceProvider.toReference}.
+ */
+interface ReferenceItem<T = unknown> {
+    /** Stable id for the underlying entity (provider scope). */
+    id: string;
+    /** Human label shown in the menu and used as the default mention chip text. */
+    label: string;
+    /** Optional secondary line (e.g. a path, table schema, owner). */
+    description?: string;
+    /** Provider-defined payload passed to {@link ReferenceProvider.toReference}. */
+    data?: T;
+}
+/**
+ * A reference that has been selected and is pending on the composer, before it
+ * is serialized onto the outgoing message.
+ */
+type PendingReference = {
+    /** Blob-capable transport discriminant. */
+    transport: "attachment";
+    /** Reference kind (e.g. `"file"`). */
+    kind: string;
+    /** Stable reference id, shared with the backend manifest. */
+    id: string;
+    /** File name shown on the chip. */
+    name: string;
+    /** MIME type of the file. */
+    mimeType: string;
+    /** Byte source: a fetchable URL, or inline base64. */
+    source: {
+        /** A fetchable URL (preferred; keeps transport and log small). */
+        url: string;
+    } | {
+        /** Inline base64 payload (fallback for small files). */
+        data: string;
+    };
+} | {
+    /** Pointer-only transport discriminant. */
+    transport: "object";
+    /** Reference kind (e.g. `"table"`), resolved by your MCP tool. */
+    kind: string;
+    /** Stable reference id, shared with the backend manifest. */
+    id: string;
+    /** Label shown on the chip. */
+    name: string;
+    /** Arbitrary extra context threaded through to the resolver. */
+    meta?: Record<string, unknown>;
+};
+/**
+ * A pluggable entry in the `@` reference menu. File upload ships as a built-in
+ * provider (see `uploadProvider`); apps register their own for entities/actions
+ * (tables, dashboards, tickets, …).
+ *
+ * A provider is either *searchable* (supplies {@link search} so its items list
+ * live in the menu) or *action-only* (omits {@link search}; selecting its group
+ * row runs {@link onSelect}, e.g. opening a file picker).
+ */
+interface ReferenceProvider<T = unknown> {
+    /** Stable provider id, e.g. `"upload" | "table" | "dashboard"`. */
+    id: string;
+    /** Group heading shown in the `@` menu. */
+    label: string;
+    /** Optional icon rendered beside the group heading. */
+    icon?: ReactNode;
+    /**
+     * Return the items to list for the current query. Omit for an action-only
+     * provider (its group row triggers {@link onSelect} directly).
+     */
+    search?: (query: string) => ReferenceItem<T>[] | Promise<ReferenceItem<T>[]>;
+    /** Custom row renderer; falls back to `label` + `description`. */
+    renderItem?: (item: ReferenceItem<T>) => ReactNode;
+    /**
+     * Side effect when an item (or the action-only group row) is chosen, e.g.
+     * opening a file dialog or running an action. Called before {@link toReference}.
+     */
+    onSelect?: (item: ReferenceItem<T>) => void | Promise<void>;
+    /**
+     * How a chosen item serializes onto the message. Omit for pure actions that
+     * produce their reference asynchronously (e.g. upload, via its own callback).
+     */
+    toReference?: (item: ReferenceItem<T>) => PendingReference;
+}
+
 /** Props for {@link KabooProvider}. */
 interface KabooProviderProps {
     /** URL of the CopilotKit runtime endpoint (e.g. `/api/copilotkit`). */
@@ -95,6 +207,11 @@ interface KabooProviderProps {
     disableInterruptHandler?: boolean;
     /** Skip auto-mounting the built-in {@link KabooInlineCards}. */
     disableInlineCards?: boolean;
+    /**
+     * `@` reference providers made available to the composer / `useReferences`.
+     * File upload is not implicit — include `uploadProvider()` to offer uploads.
+     */
+    references?: ReferenceProvider[];
     /** Extra props forwarded to the underlying `<CopilotKit>`. */
     copilotKitProps?: Partial<Omit<CopilotKitProps, "children" | "runtimeUrl" | "agent" | "threadId">>;
     /** Your app subtree, rendered inside all kaboo contexts. */
@@ -125,7 +242,7 @@ interface KabooProviderProps {
  * }
  * ```
  */
-declare function KabooProvider({ runtimeUrl, agent, threadId, structuredRenderers, interruptRenderers, disableInterruptHandler, disableInlineCards, copilotKitProps, children, }: KabooProviderProps): react.JSX.Element;
+declare function KabooProvider({ runtimeUrl, agent, threadId, structuredRenderers, interruptRenderers, disableInterruptHandler, disableInlineCards, references, copilotKitProps, children, }: KabooProviderProps): react.JSX.Element;
 
 /**
  * An open interrupt published onto the InterruptBridge so an owning agent card
@@ -243,6 +360,209 @@ declare function useActivity(): ActivityState;
  */
 declare function useDrill(): DrillState;
 
+/**
+ * Mint a stable reference id. Client-minted so the same id travels in the
+ * message/state AND is what the agent later reads from the manifest and passes
+ * to a tool. Prefixed by kind for readability in logs/manifests.
+ */
+declare function mintReferenceId(kind: string): string;
+/**
+ * The textual marker kept at a reference's mention position in the message
+ * text, so the model sees *where* each reference was cited (correlated to the
+ * manifest by id). Chip UIs render `@name`; the serialized text keeps this
+ * token.
+ */
+declare function referenceMarker(ref: PendingReference): string;
+/**
+ * Turn an `attachment`-transport reference into a CopilotKit `InputContent`
+ * part, stamping the reference id/kind/name into `metadata` so kaboo-workflows
+ * can key its registry off the same id the model reads from the manifest.
+ */
+declare function attachmentToInputContent(ref: Extract<PendingReference, {
+    transport: "attachment";
+}>): InputContent;
+/** The serialized shape of an object reference inside `state.kaboo_references`. */
+interface SerializedObjectReference {
+    /** Reference kind (e.g. `"table"`), resolved by the app's MCP tool. */
+    kind: string;
+    /** Stable reference id, shared with the backend manifest. */
+    id: string;
+    /** Human-readable label. */
+    name: string;
+    /** Arbitrary extra context threaded through to the resolver. */
+    meta?: Record<string, unknown>;
+}
+/** Project an `object`-transport reference to its wire shape. */
+declare function objectToStateEntry(ref: Extract<PendingReference, {
+    transport: "object";
+}>): SerializedObjectReference;
+/** The fully serialized outgoing payload derived from a set of pending references. */
+interface SerializedReferences {
+    /** `InputContent` parts for attachment-transport references (append after text). */
+    attachmentParts: InputContent[];
+    /** Object-transport references destined for `state.kaboo_references`. */
+    objectReferences: SerializedObjectReference[];
+}
+/** Split + serialize pending references into attachment parts and object-state entries. */
+declare function serializeReferences(refs: PendingReference[]): SerializedReferences;
+/**
+ * Merge object references into an existing AG-UI `state` under
+ * {@link REFERENCES_STATE_KEY}. Returns a new object; empty input clears the key
+ * so a prior turn's references never leak into the next run.
+ */
+declare function withReferenceState(state: Record<string, unknown> | undefined, objectReferences: SerializedObjectReference[]): Record<string, unknown>;
+/**
+ * Build the multimodal `content` array for a user message: the typed text
+ * (already containing positional markers) followed by the attachment parts.
+ * AG-UI content is an ordered array, so parts are appended after the text.
+ */
+declare function buildUserContent(text: string, attachmentParts: InputContent[]): InputContent[];
+
+/** Value exposed by {@link useReferences}. */
+interface ReferencesContextValue {
+    /** Registered `@` providers (upload built-in + app-defined). */
+    providers: ReferenceProvider[];
+    /** References currently staged on the composer. */
+    pending: PendingReference[];
+    /** Stage a reference (deduped by id). */
+    addReference: (ref: PendingReference) => void;
+    /** Remove a staged reference by id. */
+    removeReference: (id: string) => void;
+    /** Clear all staged references (call after a message is sent). */
+    clearReferences: () => void;
+    /**
+     * Object references sent with each user message, keyed by message id. Object
+     * references ride `state.kaboo_references` rather than the message content, so
+     * they'd otherwise be invisible in the sent bubble — this lets the user
+     * message renderer show them as chips.
+     */
+    messageReferences: Record<string, PendingReference[]>;
+    /** Record the object references attached to a sent user message. */
+    recordMessageReferences: (messageId: string, refs: PendingReference[]) => void;
+}
+/** Props for {@link ReferencesProvider}. */
+interface ReferencesProviderProps {
+    /** The `@` provider registry. File upload is not implicit — pass `uploadProvider()`. */
+    providers?: ReferenceProvider[];
+    /**
+     * Sync staged object-transport references into the bound agent's
+     * `state.kaboo_references` as they change, so a plain `<CopilotChat>` send
+     * still carries them. Default `true`. Attachment references travel on the
+     * message itself and are unaffected.
+     */
+    syncObjectStateTo?: string | false;
+    /** The subtree that can stage and read references. */
+    children: ReactNode;
+}
+/**
+ * Holds the `@` reference registry and the composer's staged references, and
+ * (by default) mirrors object references into the agent's AG-UI state. Mounted
+ * automatically by {@link KabooProvider}; read it via {@link useReferences}.
+ */
+declare function ReferencesProvider({ providers, syncObjectStateTo, children, }: ReferencesProviderProps): react.JSX.Element;
+/**
+ * Mirrors staged object-transport references into the bound agent's
+ * `state.kaboo_references`. Mounted by {@link ReferencesProvider} when
+ * `syncObjectStateTo` is set.
+ */
+declare function ReferenceStateSync({ agentId, pending, }: {
+    agentId?: string;
+    pending: PendingReference[];
+}): null;
+/**
+ * Access the `@` reference registry and staged references.
+ *
+ * @example
+ * ```tsx
+ * const { providers, pending, addReference } = useReferences();
+ * ```
+ */
+declare function useReferences(): ReferencesContextValue;
+
+type CopilotInputProps = ComponentProps<typeof CopilotChatInput>;
+/**
+ * Props for {@link KabooReferenceInput}. This is a drop-in value for
+ * `<CopilotChat input={…}>`, so it receives every prop CopilotKit hands the
+ * input slot (value, onChange, onSubmitMessage, …) plus a couple of
+ * kaboo-specific knobs.
+ */
+interface KabooReferenceInputProps extends CopilotInputProps {
+    /** Character that opens the reference popover from the editor. Default `"@"`. */
+    trigger?: string;
+}
+/**
+ * A `<CopilotChat input={…}>` slot that keeps CopilotKit's native input chrome
+ * (send button, disclaimer, theme, layout) but replaces the plain textarea with
+ * a lightweight rich editor. References — your objects (via `@`) and files (via
+ * the `+` button or the "attach a file" row) — render as interactive inline
+ * chips: click a chip to swap it for another, or its `×` to remove it. The `+`
+ * and `@` triggers open the *same* searchable popover. Object references ride
+ * `state.kaboo_references` (agent sees them inline as `@name`); files ride the
+ * message as attachment parts (agent is made aware via the manifest). On submit
+ * the editor builds the multimodal message and runs the agent.
+ *
+ * @example
+ * ```tsx
+ * <KabooProvider references={[uploadProvider({ onUpload }), tableProvider]} …>
+ *   <CopilotChat input={KabooReferenceInput} />
+ * </KabooProvider>
+ * ```
+ */
+declare function KabooReferenceInput({ trigger, ...inputProps }: KabooReferenceInputProps): react.JSX.Element;
+
+/** Configuration for the built-in file {@link uploadProvider}. */
+interface UploadProviderConfig {
+    /** Provider id in the `@` menu. Default `"upload"`. */
+    id?: string;
+    /** Group label in the `@` menu. Default `"Upload"`. */
+    label?: string;
+    /** Reference kind stamped on emitted attachments. Default `"file"`. */
+    kind?: string;
+    /** `accept` filter for the file picker (e.g. `"image/*,.pdf"`). */
+    accept?: string;
+    /** Max file size in bytes. Files above this are rejected. Default 20MB. */
+    maxSize?: number;
+    /**
+     * Store the file and return a fetchable source. Return a `url` (presigned or
+     * public — the server fetches it with no auth) or inline `data` (base64).
+     * When omitted, the file is inlined as base64 (fine for small files/tests,
+     * bloats the event log for large ones).
+     */
+    onUpload?: (file: File) => AttachmentUploadResult | Promise<AttachmentUploadResult>;
+}
+/** Internal marker: identifies a {@link ReferenceProvider} produced by {@link uploadProvider}. */
+declare const UPLOAD_MARKER: "__kabooUpload";
+/** A {@link ReferenceProvider} carrying its resolved upload config for the composer. */
+interface UploadReferenceProvider extends ReferenceProvider {
+    /** Resolved upload config the composer reads to drive the file picker. */
+    [UPLOAD_MARKER]: Required<Pick<UploadProviderConfig, "kind" | "maxSize">> & Pick<UploadProviderConfig, "accept" | "onUpload">;
+}
+/**
+ * Upload one file and return the pending attachment reference (id minted here).
+ * Uses `config.onUpload` when provided, else inlines the bytes as base64.
+ */
+declare function uploadFileToReference(file: File, config: UploadProviderConfig): Promise<PendingReference>;
+/**
+ * Built-in file-upload {@link ReferenceProvider}. Action-only: choosing it in
+ * the `@` menu opens the file picker; the composer uploads the file (via
+ * `onUpload` or base64) and adds an `attachment`-transport reference.
+ *
+ * @example
+ * ```tsx
+ * <KabooProvider references={[uploadProvider({ accept: "image/*,.pdf", onUpload })]} ...>
+ * ```
+ */
+declare function uploadProvider(config?: UploadProviderConfig): UploadReferenceProvider;
+/** Narrow a provider to an {@link UploadReferenceProvider}. */
+declare function isUploadProvider(provider: ReferenceProvider): provider is UploadReferenceProvider;
+/**
+ * Build a CopilotKit `AttachmentsConfig` from an upload config, wrapping
+ * `onUpload` so every uploaded file carries kaboo id/kind/name in its
+ * `InputContent` metadata. Pass to `<CopilotChat attachments={...}>` to use
+ * CopilotKit's native attachment UI instead of the `@` composer.
+ */
+declare function buildAttachmentsConfig(config?: UploadProviderConfig): AttachmentsConfig;
+
 /** A `[groupId, group]` pair, as returned by the group-hierarchy helpers. */
 type GroupEntry = [string, StreamGroup];
 /**
@@ -554,4 +874,4 @@ declare function formatToolResult(raw: string): {
  */
 declare function normalizeResult(result: string | undefined): string | null;
 
-export { type ActiveInterrupt, ActivityPanel, ActivityState, AgentCard, type AgentCardProps, DrillDetailView, DrillProvider, DrillState, GlassTabs, type GroupEntry, InterruptBridgeProvider, InterruptBridgePublisher, InterruptReason, InterruptRenderer, InterruptRendererProps, KabooActivityProvider, type KabooActivityProviderProps, KabooProvider, type KabooProviderProps, MarkdownContent, MiniTable, StreamGroup, type StructuredRenderers, StructuredRenderersContext, Timeline, TimelineEntry, type TimelineProps, ToolCall, ToolRow, directChildren, formatToolInput, formatToolResult, normalizeResult, topLevelGroups, useActivity, useDrill, useInterruptBridge, useInterruptFor };
+export { type ActiveInterrupt, ActivityPanel, ActivityState, AgentCard, type AgentCardProps, DrillDetailView, DrillProvider, DrillState, GlassTabs, type GroupEntry, InterruptBridgeProvider, InterruptBridgePublisher, InterruptReason, InterruptRenderer, InterruptRendererProps, KabooActivityProvider, type KabooActivityProviderProps, KabooProvider, type KabooProviderProps, KabooReferenceInput, type KabooReferenceInputProps, MarkdownContent, MiniTable, type PendingReference, REFERENCES_STATE_KEY, REFERENCE_METADATA_KEYS, type ReferenceItem, type ReferenceProvider, ReferenceStateSync, type ReferenceTransport, type ReferencesContextValue, ReferencesProvider, type ReferencesProviderProps, type SerializedObjectReference, type SerializedReferences, StreamGroup, type StructuredRenderers, StructuredRenderersContext, Timeline, TimelineEntry, type TimelineProps, ToolCall, ToolRow, UPLOAD_MARKER, type UploadProviderConfig, type UploadReferenceProvider, attachmentToInputContent, buildAttachmentsConfig, buildUserContent, directChildren, formatToolInput, formatToolResult, isUploadProvider, mintReferenceId, normalizeResult, objectToStateEntry, referenceMarker, serializeReferences, topLevelGroups, uploadFileToReference, uploadProvider, useActivity, useDrill, useInterruptBridge, useInterruptFor, useReferences, withReferenceState };