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;
  };
}
  • state is isolated per extension id and serialised as JSON.
  • publish feeds the brief and targeted reads. It is a summary, never content.
  • services and events are registry-global; every contribution is removed on deactivate.
  • tabs.openTile applies the tile type's prepare and 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, number and boolean inputs; 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 requires is hidden when a service is missing;
  • mutates is 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

IdentifierKindProvided by
terminal.open@1serviceTerminal
terminal.sessions@1serviceTerminal
terminal.session.closedeventTerminal
markdown.open@1serviceMarkdown
markdown.documents@1serviceMarkdown
markdown.document.savedeventMarkdown
data.tables@1serviceData
data.charts@1serviceData
data.table.changedeventData
preview.pdf@1servicePreview
spark.notifications@1serviceCore

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.