SDK d’extension

Une tuile, c’est un composant React et un contrat. Le contrat est ce que voit un agent : un titre, un guide court, une description d’une ligne et des actions typées qu’il peut appeler.

Manifeste

interface Manifest {
  id: string;              // stable, préfixé : "demo.hello"
  name: string;
  version: string;         // x.y.z
  icon?: IconComponent;    // composant Lucide pour les intégrées
  color?: string;          // teinte spectrale
  tier?: "core" | "official" | "community";
  tileTypes?: readonly string[];
  summary?: string;
  description?: string;
  category?: string;
  subtitle?: string;
  screenshots?: readonly string[];
  certification?: "spark";
}

Les extensions intégrées exportent cet objet depuis manifest.ts. Les paquets importés utilisent un extension.json sérialisable, converti vers la même forme ; voir Paquets et dépôts.

API

interface SparkAPI {
  state: {
    read(): unknown;
    save(value: unknown): void;          // JSON, isolé par identifiant d'extension
  };
  tiles: {
    register(definition: TileDefinition): Dispose;
    publish(tileId: string, surface: TileSurface): void; // ≤ 2 000 caractères, non persisté
  };
  commands: { register(command: Command): Dispose };
  services: {
    provide<T>(key: ServiceKey<T>, service: T): Dispose;
    get<T>(key: ServiceKey<T>): T | undefined;
  };
  events: {
    on<T>(key: EventKey<T>, listener: (value: T) => void): Dispose;
    emit<T>(key: EventKey<T>, value: T): void;
  };
  tabs: {
    openTile(type: string, data?: Data, alongside?: string): Tile;
    focusTile(id: string): void;
    updateTileData(id: string, data: Data): void;
    getTiles(): Tile[];
    getAllTiles(): Tile[];
    getFocusedTile(): Tile | undefined;
  };
}
  • state est isolé par identifiant d’extension et sérialisé en JSON.
  • publish alimente le brief et les lectures ciblées. C’est un résumé, jamais du contenu.
  • services et events sont globaux au registre ; chaque contribution est retirée au deactivate.
  • tabs.openTile applique le prepare du type de tuile et ajoute la tuile à l’onglet demandé.

Tuile

interface TileDefinition {
  type: string;                 // "demo.hello.tile"
  title: string;
  icon?: IconComponent;
  dataKeys?: readonly string[];
  guide?: string;               // ≤ 1 200 caractères, livré une fois par session
  prepare?(data: Data): Data;
  describe?(tile: Tile, surface: TileSurface): string;
  actions?: Record<string, TileAction>;
  canClose?(tile: Tile, closing: ReadonlySet<string>): boolean | Promise<boolean>;
  close?(tile: Tile): void | Promise<void>;
}

guide est un mode d’emploi pour un agent, pas du marketing. Il est plafonné à 1 200 caractères et livré une seule fois par session.

Action

interface TileAction {
  title: string;
  description?: string;
  input?: Record<string, ActionField>;   // string | number | boolean
  requires?: readonly ServiceKey<unknown>[];
  mutates?: boolean | ((tile: Tile) => boolean);
  run(tile: Tile, input: Record<string, ActionValue>): unknown | Promise<unknown>;
}

Le registre applique, à l’appel :

  • nom d’action conforme à ^[a-z][a-z0-9_.-]*$, champ conforme à ^[a-z][a-zA-Z0-9_]*$ ;
  • entrées string, number ou boolean uniquement ; un argument inconnu, manquant ou mal typé est refusé ;
  • nombres finis, enum respecté ;
  • résultat JSON plafonné à 16 000 caractères ;
  • une action avec requires est masquée si le service manque ;
  • mutates est signalé au client MCP, qui décide de demander confirmation.

Commande

interface Command {
  id: string;
  title: string;
  icon?: IconComponent;
  category?: string;
  tileType?: string;        // apparaît aussi dans le rail si épinglée
  keywords?: string[];
  dev?: boolean;            // mode développeur uniquement
  run(): unknown | Promise<unknown>;
}

Une commande avec tileType apparaît dans le rail quand elle est épinglée, et dans⌘K. Une commande dev n’apparaît qu’en mode développeur.

Vue

type TileView = React.ComponentType<{ tile: Tile; active: boolean }>;

interface ExtensionModule {
  activate(api: ExtensionAPI): void | Promise<void>;
  deactivate?(): void | Promise<void>;
}

ExtensionAPI est SparkAPI avec tiles.register enrichi deview. L’hôte monte votre composant dans dockview.

Une tuile minimale

import type { ExtensionModule } from "../../sdk";

export default function createHello(): ExtensionModule {
  return {
    activate(api) {
      api.tiles.register({
        type: "demo.hello.tile",
        title: "Hello",
        dataKeys: ["name"],
        guide: "Tuile de démonstration. Aucune action.",
        view: ({ tile }) => <p>Bonjour {tile.data.name ?? "le monde"}</p>,
      });
    },
  };
}

Services et événements

IdentifiantTypeFourni par
terminal.open@1serviceTerminal
terminal.sessions@1serviceTerminal
terminal.session.closedévénementTerminal
markdown.open@1serviceMarkdown
markdown.documents@1serviceMarkdown
markdown.document.savedévénementMarkdown
data.tables@1serviceDonnées
data.charts@1serviceDonnées
data.table.changedévénementDonnées
preview.pdf@1serviceAperçu
spark.notifications@1serviceNoyau

get renvoie undefined pour un service absent : vous pouvez en consommer un qui n’est pas là. Une action qui le déclare dans requires n’est simplement pas proposée.

Conventions

  • Préfixer les types de tuiles, les identifiants de commandes et les clés par l’identifiant de l’extension.
  • Ne jamais mettre de contenu lourd dans une surface, un brief ou un résultat d’action.
  • Une vue doit survivre à ses propres erreurs : la barrière de tuile est un filet, pas un contrôle de flux.