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;
};
}stateest isolé par identifiant d’extension et sérialisé en JSON.publishalimente le brief et les lectures ciblées. C’est un résumé, jamais du contenu.serviceseteventssont globaux au registre ; chaque contribution est retirée audeactivate.tabs.openTileapplique lepreparedu 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,numberoubooleanuniquement ; un argument inconnu, manquant ou mal typé est refusé ; - nombres finis, enum respecté ;
- résultat JSON plafonné à 16 000 caractères ;
- une action avec
requiresest masquée si le service manque ; mutatesest 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
| Identifiant | Type | Fourni par |
|---|---|---|
terminal.open@1 | service | Terminal |
terminal.sessions@1 | service | Terminal |
terminal.session.closed | événement | Terminal |
markdown.open@1 | service | Markdown |
markdown.documents@1 | service | Markdown |
markdown.document.saved | événement | Markdown |
data.tables@1 | service | Données |
data.charts@1 | service | Données |
data.table.changed | événement | Données |
preview.pdf@1 | service | Aperçu |
spark.notifications@1 | service | Noyau |
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.