ghostykit 0.6.4 → 0.7.1

package/dist/react/plugins.d.ts

@@ -0,0 +1,249 @@
+import type { ComponentType, ReactNode } from "react";
+import type { BaseEvent } from "@ag-ui/core";
+import type { TextBlock } from "../core/narration";
+import type { ToolVerbs } from "../core/steps";
+import type { Attachment, CustomEntry, PilotState, Reference, ToolEntry, Turn } from "../core/types";
+import type { UploadResult } from "./Composer";
+import type { MarkdownOptions, PilotIcon } from "./context";
+import type { PilotStrings } from "./strings";
+import type { Pilot, TurnDoneInfo } from "./usePilot";
+/** Lo que todo plugin recibe: el piloto, el estado del agente y las acciones del chat. */
+export interface PluginCtx {
+    pilot: Pilot;
+    /** `pilot.state.agentState`, a la mano. */
+    agentState: Record<string, unknown>;
+    strings: PilotStrings;
+    send: (text: string, attachments?: Attachment[]) => void;
+    addReference: (ref: Reference) => void;
+    /** Escribe en la caja sin mandar. */
+    setDraft: (text: string) => void;
+    /**
+     * Agrega adjuntos a la caja, como si la persona los eligiera: `File` pasa por `upload`; un
+     * `Attachment` (ya subido, p. ej. de «Mis archivos») va tal cual. Se mandan con o sin texto.
+     */
+    addAttachments: (items: (File | Attachment)[]) => void;
+    /** Pone el foco en la caja. */
+    focus: () => void;
+    /** Los plugins montados, en orden. */
+    plugins: readonly PilotoPlugin[];
+}
+/** Un componente de plugin: recibe `ctx` y, según el punto, lo que dibuja. */
+export type PluginView<P = object> = ComponentType<P & {
+    ctx: PluginCtx;
+}>;
+/** Un evento AG-UI como lo recibe `events` (los CUSTOM traen `name` y `value`). */
+export type PluginEvent = BaseEvent & {
+    name?: string;
+    value?: unknown;
+    [k: string]: unknown;
+};
+/** El markdown de las respuestas, desde un plugin. */
+export interface PluginMarkdown {
+    /** Reescribe el markdown antes de pintarlo, con el turno a la mano. Se encadena en orden. */
+    transform?: (md: string, turn?: Turn) => string;
+    /** Un clic en un enlace: `true` si el plugin lo manejó. Se pregunta en orden. */
+    onLinkClick?: MarkdownOptions["onLinkClick"];
+    /**
+     * Bloques con nombre del texto (```eb-file …```) que se pintan como tarjeta y salen del markdown,
+     * por su nombre. Uno a medio escribir llega con `complete: false`.
+     */
+    blocks?: Record<string, PluginView<{
+        block: TextBlock;
+        turn: Turn;
+        live: boolean;
+    }>>;
+    /**
+     * Cómo se pinta un elemento del markdown, por etiqueta (`a`, `code`, `img`…): p. ej. un enlace que
+     * es un CTA como botón. Recibe las props del elemento y `ctx`. Por etiqueta, gana el primer plugin.
+     */
+    components?: Record<string, ComponentType<Record<string, unknown> & {
+        ctx: PluginCtx;
+        children?: ReactNode;
+    }>>;
+}
+/** Un rechazo HTTP del servidor antes del stream (403 con `x-needs-login`, 429…). */
+export type PluginHttpError = NonNullable<PilotState["httpError"]>;
+export interface PilotoPlugin {
+    /** Único: aparece en `data-plugin`, en los avisos y en `pilotDevtools()`. */
+    name: string;
+    /**
+     * De quién son los estilos de lo que dibuja. `host` (default): de la app; las utilidades de
+     * ghostykit no lo tocan. `ghostykit`: usa las clases de ghostykit (para componentes de ghostykit
+     * como `<Subagents>` o `ModelPicker`).
+     */
+    styles?: "host" | "ghostykit";
+    /**
+     * Lo que el plugin atiende, como documentación visible. Si falta, se deriva de `events`, `state` y
+     * `message.custom`; si está y no coincide, en desarrollo se avisa.
+     */
+    requires?: {
+        events?: string[];
+        state?: string[];
+    };
+    /** Textos (se combinan sobre los del idioma). */
+    strings?: Partial<PilotStrings>;
+    markdown?: PluginMarkdown;
+    /** Variables `--piloto-*` y clases extra para la raíz (branding fino sobre la piel). */
+    vars?: Record<string, string>;
+    className?: string;
+    tools?: {
+        /** Cómo se nombra cada herramienta (`one`, `many`, `running`). */
+        verbs?: ToolVerbs;
+        /** Ícono por nombre de herramienta o por `kind`. */
+        icons?: Record<string, PilotIcon>;
+        /** Una vista propia por nombre de herramienta (p. ej. la vista previa de `create_image`), bajo los pasos. */
+        render?: Record<string, PluginView<{
+            tool: ToolEntry;
+            turn: Turn;
+            live: boolean;
+        }>>;
+    };
+    /** Por tipo AG-UI (`STATE_DELTA`), por nombre de CUSTOM (`ghosty.page`) o `*` para todos. */
+    events?: Record<string, (event: PluginEvent, ctx: PluginCtx) => void>;
+    /** Por llave de `agentState` (`model`, `subagents`): se llama cuando cambia. */
+    state?: Record<string, (value: unknown, ctx: PluginCtx) => void>;
+    message?: {
+        /** Bajo cada mensaje del usuario. */
+        user?: PluginView<{
+            turn: Turn;
+        }>;
+        /** Bajo cada respuesta. */
+        assistant?: PluginView<{
+            turn: Turn;
+            live: boolean;
+        }>;
+        /** Antes del texto de cada respuesta, bajo sus pasos (avance de una página, «creando imagen»). */
+        assistantBefore?: PluginView<{
+            turn: Turn;
+            live: boolean;
+        }>;
+        /** Una entrada de `turn.custom` por su nombre (`ghosty.delivery`, tarjetas CRM…). */
+        custom?: Record<string, PluginView<{
+            entry: CustomEntry;
+            turn: Turn;
+            live: boolean;
+        }>>;
+        /** El texto del usuario como se pinta (se encadena en orden). */
+        formatUserText?: (text: string) => string;
+        /** El texto que sale, antes de mandarlo (p. ej. anteponer lo señalado). Se encadena en orden. */
+        beforeSend?: (text: string, ctx: PluginCtx) => string;
+        /** El avatar del agente junto a cada respuesta. Gana el primer plugin. */
+        avatar?: PluginView<{
+            turn: Turn;
+        }>;
+    };
+    composer?: {
+        /** Botones en la barra del composer, entre la imagen y el clip («Mis archivos», «Señalar»). */
+        actions?: PluginView;
+        /** Botones en la barra del composer, después del clip (selector de modelo). */
+        actionsEnd?: PluginView;
+        /** Bajo la caja (chips de sugerencias en el hilo vacío). */
+        below?: PluginView;
+        /** Pegado arriba de la caja (chips, avisos, subagentes). */
+        above?: PluginView;
+        /** Adjuntos y voz. */
+        attachments?: {
+            upload?: (file: File) => Promise<UploadResult>;
+            transcribe?: (audio: Blob) => Promise<string>;
+            voiceNoteText?: (transcript: string) => string;
+            /** Qué se puede adjuntar (como el `accept` de un input): `"image/*"` = sólo fotos. */
+            accept?: string;
+            /** Cuántos archivos a la vez (default 8). */
+            maxFiles?: number;
+            /** Tamaño máximo por archivo, en bytes (default 25 MB). */
+            maxBytes?: number;
+        };
+        /**
+         * En lugar de la caja, cuando `when(ctx)` es verdad (p. ej. la prueba se acabó: 403 con
+         * `x-needs-login` → «Crea tu cuenta»). Gana el primer plugin cuyo `when` es verdad.
+         */
+        replace?: {
+            when: (ctx: PluginCtx) => boolean;
+            view: PluginView;
+        };
+    };
+    /** Arriba a la derecha, sobre el hilo. */
+    header?: PluginView;
+    /** Junto al chat. */
+    sidePanel?: PluginView;
+    /** Arriba de los mensajes, dentro del hilo. */
+    aboveThread?: PluginView;
+    /** El hilo vacío (en lugar del saludo). */
+    empty?: PluginView;
+    /** Lo que se ve mientras el agente no contesta (en lugar de la frase de espera). */
+    waiting?: PluginView<{
+        step: string | null;
+        since: number;
+    }>;
+    /** Envuelve TODO el chat (un proveedor: panel de artefactos, contexto propio). El primero va afuera. */
+    wrap?: ComponentType<{
+        ctx: PluginCtx;
+        children: ReactNode;
+    }>;
+    /** El servidor rechazó un mensaje antes de contestar (`ctx.pilot.state.httpError` también lo guarda). */
+    onHttpError?: (error: PluginHttpError, ctx: PluginCtx) => void;
+    /** Este cliente mandó un turno. */
+    onTurnStart?: (ctx: PluginCtx) => void;
+    /** Terminó un turno de este cliente (abrir la última entrega, re-leer datos). */
+    onTurnDone?: (info: TurnDoneInfo, ctx: PluginCtx) => void;
+}
+/** Ayuda de tipos: `definePlugin({ name: "crm", … })`. */
+export declare function definePlugin<T extends PilotoPlugin>(plugin: T): T;
+type Owned<T> = {
+    plugin: string;
+    value: T;
+};
+/** Los plugins ya combinados: lo que lee <Piloto>. */
+export interface ResolvedPlugins {
+    list: readonly PilotoPlugin[];
+    strings: Partial<PilotStrings>;
+    verbs: ToolVerbs;
+    icons: Record<string, PilotIcon>;
+    markdown: MarkdownOptions;
+    formatUserText?: (text: string) => string;
+    vars: Record<string, string>;
+    className: string;
+    toolRenders: Record<string, Owned<NonNullable<NonNullable<PilotoPlugin["tools"]>["render"]>[string]>>;
+    customRenders: Record<string, Owned<NonNullable<NonNullable<PilotoPlugin["message"]>["custom"]>[string]>>;
+    blockRenders: Record<string, Owned<NonNullable<PluginMarkdown["blocks"]>[string]>>;
+    components: Record<string, Owned<NonNullable<PluginMarkdown["components"]>[string]>>;
+    avatar?: Owned<NonNullable<NonNullable<PilotoPlugin["message"]>["avatar"]>>;
+    beforeSend?: (text: string, ctx: PluginCtx) => string;
+    replacers: Owned<NonNullable<NonNullable<PilotoPlugin["composer"]>["replace"]>>[];
+    httpError: Owned<NonNullable<PilotoPlugin["onHttpError"]>>[];
+    attachments: NonNullable<NonNullable<PilotoPlugin["composer"]>["attachments"]>;
+    empty?: Owned<PluginView>;
+    waiting?: Owned<NonNullable<PilotoPlugin["waiting"]>>;
+    header: Owned<PluginView>[];
+    sidePanel: Owned<PluginView>[];
+    aboveThread: Owned<PluginView>[];
+    composerActions: Owned<PluginView>[];
+    composerAbove: Owned<PluginView>[];
+    composerActionsEnd: Owned<PluginView>[];
+    composerBelow: Owned<PluginView>[];
+    messageBefore: Owned<NonNullable<NonNullable<PilotoPlugin["message"]>["assistantBefore"]>>[];
+    wraps: Owned<NonNullable<PilotoPlugin["wrap"]>>[];
+    turnStart: Owned<NonNullable<PilotoPlugin["onTurnStart"]>>[];
+    turnDone: Owned<NonNullable<PilotoPlugin["onTurnDone"]>>[];
+    /** Los plugins cuyos dibujos usan los estilos de ghostykit (`styles: "ghostykit"`). */
+    ghostykitStyled: Set<string>;
+    messageUser: Owned<NonNullable<NonNullable<PilotoPlugin["message"]>["user"]>>[];
+    messageAssistant: Owned<NonNullable<NonNullable<PilotoPlugin["message"]>["assistant"]>>[];
+    events: Record<string, Owned<NonNullable<PilotoPlugin["events"]>[string]>[]>;
+    state: Record<string, Owned<NonNullable<PilotoPlugin["state"]>[string]>[]>;
+    /** Choques y declaraciones que no cuadran (se avisan en desarrollo). */
+    warnings: string[];
+}
+/** Lo que atiende un plugin: lo declarado en `requires` o, si falta, lo que se deriva de sus puntos. */
+export declare function pluginRequires(p: PilotoPlugin): {
+    events: string[];
+    state: string[];
+};
+/** Los puntos de extensión que usa un plugin, por nombre (para `pilotDevtools()` y los avisos). */
+export declare function pluginPoints(p: PilotoPlugin): string[];
+export declare function resolvePlugins(list?: readonly PilotoPlugin[]): ResolvedPlugins;
+/** Los CUSTOM que ghostykit atiende solo (no hace falta un plugin para ellos). */
+export declare const BUILTIN_CUSTOM: Set<string>;
+/** En desarrollo (lo decide el bundler de la app con `process.env.NODE_ENV`). */
+export declare function isDev(): boolean;
+export {};

package/dist/react/usePilot.d.ts

@@ -12,6 +12,13 @@ export interface TurnDoneInfo {
     /** El run se detuvo a pedir aprobación. */
     interrupted?: boolean;
 }
+/** El inicio o el fin de un turno de este cliente. */
+export type TurnEvent = {
+    type: "start";
+} | {
+    type: "done";
+    info: TurnDoneInfo;
+};
 export interface UsePilotOptions {
     /** El hilo (AG-UI `threadId`). Con él, al montar se pide el hilo guardado (MESSAGES_SNAPSHOT). Sin él, hilo nuevo. */
     threadId?: string;
@@ -29,6 +36,8 @@ export interface UsePilotOptions {
     onTitle?: (title?: string) => void;
     /** Cada evento AG-UI crudo, antes del reductor (analítica, STATE_*, CUSTOM propios). */
     onEvent?: (event: BaseEvent) => void;
+    /** Un mensaje que sale solo en cuanto el hilo está abierto (p. ej. `?enviar=1` con la pregunta en la URL). */
+    initialPrompt?: string;
     /** Cada run que sale (analítica). */
     onSend?: (input: RunAgentInput) => void;
     /** El estado del agente cambió (`STATE_SNAPSHOT` / `STATE_DELTA` ya aplicado). */
@@ -82,6 +91,12 @@ export interface Pilot {
      * por fuera que algo cambió (p. ej. el bus `/me/events` avisa que un subagente terminó).
      */
     refresh: () => Promise<void>;
+    /** Vuelve a leer el hilo (igual que `refresh`): para una reconexión que decide la app (p. ej. su bus de eventos). */
+    reconnect: () => Promise<void>;
+    /** Escucha el inicio y el fin de cada turno de este cliente. Regresa cómo dejar de escuchar. */
+    onTurn: (listener: (event: TurnEvent) => void) => () => void;
+    /** Escucha cada evento AG-UI de este piloto (como `onEvent`, pero desde afuera). Regresa cómo dejar de escuchar. */
+    subscribe: (listener: (event: BaseEvent) => void) => () => void;
     /** Continúa el run que el servidor cortó (`state.cutRun`): `forwardedProps.continueRun`. */
     continueRun: () => Promise<void>;
 }