@decisive.rocks/sdk

Build extensions for Decisive. A plugin lives in a .decisive/ folder in your connected repo, declares capabilities with define*(), describes its UI with Block Kit, and talks to Decisive through a versioned host API (ctx.*). Decisive syncs it from your repo, runs handlers in a sandbox, and renders the UI natively — so extensions stay consistent and platform updates don't break them.

Architecture & rationale: see ../EXTENSIONS.md.

The shape

import { definePlugin, defineTool } from '@decisive.rocks/sdk';

export default definePlugin({
  name: 'orders',
  apiVersion: 1,
  secrets: [{ key: 'SHOP_API_KEY', label: 'Shop API key', required: true }],
  actions: [
    defineTool<{ id: string }>({
      name: 'lookup_order',
      description: 'Look up an order by id.',
      input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
      needs: ['SHOP_API_KEY'],
      async run(input, ctx) {
        const res = await ctx.http(`https://api.shop.com/orders/${input.id}`, {
          headers: { authorization: `Bearer ${ctx.secrets.SHOP_API_KEY}` }
        });
        return { data: await res.json() };
      }
    })
  ]
});

Core ideas

• The action is the atom. One capability, bound to any of: the AI (ai-tool), the coding agents (agent-runner), a slash-command:/x, a panel, a chat-action.
• Declarative UI. Return Blocks; Decisive renders them. Interactions come back to onAction. When blocks aren't enough, a canvas panel (definePanel({ mount })) owns the DOM of a visible sandboxed document that boots with Decisive's design system (live theme tokens, brand fonts, native-styled elements) plus window.decisive — brand-native charts (decisive.chart: line, area, bar, stacked-bar, donut, sparkline), a DOM builder, and theme events. Full UI freedom, same security envelope.
• Stable boundary. Everything a plugin can see or do is on ctx (context, chat, tasks, pages, ai, http, store, secrets, ui). Plugins never touch Decisive internals, so internals can change without breaking you.
• Code in repo, secrets in Decisive. Declare secrets; an admin fills them; they're injected at runtime. Never commit them.

Capability helpers

| Helper | Declares | | --- | --- | | defineAction / defineTool | a capability + optional interactive UI | | defineContextSource | scheduled pull of external data into context | | definePanel | a workspace tab — render (blocks) or mount (canvas: your own UI on the design system) | | defineWebhook | an inbound, signature-verified webhook | | definePlugin | bundles the above + metadata + declared secrets |

Examples

• examples/content-generator — actions-out, multi-surface, interactive.
• examples/intercom-pain-points — context-in, on-demand tool + panel.
• examples/knowledge-sync — ambient context via a scheduled source.