Extension SDK
A tile is a React component plus a contract. The contract is what an agent sees: a title, a short guide, a one-line description, and typed actions it can call.
Manifest
interface Manifest {
id: string; // stable, prefixed: "demo.hello"
name: string;
version: string; // x.y.z
icon?: IconComponent; // Lucide component for built-ins
color?: string; // spectral tint
tier?: "core" | "official" | "community";
tileTypes?: readonly string[];
summary?: string;
description?: string;
category?: string;
subtitle?: string;
screenshots?: readonly string[];
certification?: "spark";
}Built-in extensions export this object from manifest.ts. Imported packages use a serialisable extension.json that is converted to the same shape; seePackages and registries.
API
interface SparkAPI {
state: {
read(): unknown;
save(value: unknown): void; // JSON, scoped to the extension id
};
tiles: {
register(definition: TileDefinition): Dispose;
publish(tileId: string, surface: TileSurface): void; // ≤ 2,000 chars, not persisted
};
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;
};
}stateis isolated per extension id and serialised as JSON.publishfeeds the brief and targeted reads. It is a summary, never content.servicesandeventsare registry-global; every contribution is removed ondeactivate.tabs.openTileapplies the tile type'sprepareand adds the tile to the requested tab.
Tile
interface TileDefinition {
type: string; // "demo.hello.tile"
title: string;
icon?: IconComponent;
dataKeys?: readonly string[];
guide?: string; // ≤ 1,200 chars, delivered once per 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 is a working manual for an agent, not marketing. It is capped at 1,200 characters and delivered once per 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>;
}The registry enforces, at call time:
- action names match
^[a-z][a-z0-9_.-]*$; fields match^[a-z][a-zA-Z0-9_]*$; - only
string,numberandbooleaninputs; unknown, missing or mistyped arguments are refused; - numbers must be finite, enums must match;
- the JSON result is capped at 16,000 characters;
- an action with
requiresis hidden when a service is missing; mutatesis reported to the MCP client, which decides whether to ask for confirmation.
Command
interface Command {
id: string;
title: string;
icon?: IconComponent;
category?: string;
tileType?: string; // also appears in the rail when pinned
keywords?: string[];
dev?: boolean; // developer mode only
run(): unknown | Promise<unknown>;
}A command with a tileType appears in the rail when pinned, and in ⌘K. A dev command only appears in developer mode.
View
type TileView = React.ComponentType<{ tile: Tile; active: boolean }>;
interface ExtensionModule {
activate(api: ExtensionAPI): void | Promise<void>;
deactivate?(): void | Promise<void>;
}ExtensionAPI is SparkAPI with tiles.register extended byview. The host mounts your component inside dockview.
A minimal tile
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: "Demo tile. No actions.",
view: ({ tile }) => <p>Hello {tile.data.name ?? "world"}</p>,
});
},
};
}Services and events
| Identifier | Kind | Provided by |
|---|---|---|
terminal.open@1 | service | Terminal |
terminal.sessions@1 | service | Terminal |
terminal.session.closed | event | Terminal |
markdown.open@1 | service | Markdown |
markdown.documents@1 | service | Markdown |
markdown.document.saved | event | Markdown |
data.tables@1 | service | Data |
data.charts@1 | service | Data |
data.table.changed | event | Data |
preview.pdf@1 | service | Preview |
spark.notifications@1 | service | Core |
get returns undefined for a missing service: you may consume one that is not there. An action that declares it in requires is simply not offered.
Conventions
- Prefix tile types, command ids and keys with your extension id.
- Never put heavy content in a surface, a brief or an action result.
- A view must survive its own errors: the tile error boundary is a safety net, not control flow.