Plugins SDK

The Platform Extension SDK lets builders sell and ship bots, agents, strategies, UI packs, skills, and analytics plugins that run inside Alphonce — with full product capabilities, never unrestricted account access.

Using the SDK

import {
  validateManifest,
  assertCapabilities,
  createPluginApiClient,
  applyUiTokens,
} from '@alphonce/plugins'

const parsed = validateManifest(rawJson)
if (!parsed.ok) throw new Error(parsed.errors.join(', '))

const gate = assertCapabilities(granted, ['portfolio:read'])
if (!gate.ok) throw new Error('Missing ' + gate.missing.join(', '))

const api = createPluginApiClient(granted)
// Hits /api/plugins/* (portfolio, strategies, rebalance, prefs) — never billing/vault
const summary = await api.getPortfolioSummary()

// UI packs — CSS variables + desk slots consumed by /asset
applyUiTokens({ density: 'compact', accent: '#6B4EF5' })

Product types

Every pack declares one type in its manifest:

Manifest

Packs ship a machine-readable manifest. Capabilities listed here are what the install UI asks the user to approve.

{
  "id": "example.morning-brief",
  "name": "Morning Research Brief",
  "version": "1.0.0",
  "type": "agent",
  "entry": "./dist/index.js",
  "capabilities": ["portfolio:read", "analysis:read", "agent:hooks"],
  "preview": {
    "blurb": "Daily brief from holdings and market context.",
    "image": "./preview.png"
  },
  "pricing": {
    "model": "free"
  }
}

Capability model

Scopes mirror the MCP permission gate. A pack may only call APIs covered by capabilities the user granted at install. Request the minimum set.

Sandbox runtime

• No raw network or cookies — outbound I/O goes through mediated Alphonce APIs only.
• No unrestricted DOM — UI packs apply tokens and layout slots; they do not inject arbitrary HTML into trading chrome.
• Timeouts — long-running compute is killed (analytics plugins: Worker + 3s limit inside an opaque iframe).
• Data-only analytics returns — metrics, series, and plain-text notes. Never markup (XSS surface).

Lifecycle

1. Develop against the SDK and declare capabilities.
2. Publish for review (strategy listings already use the seller flow).
3. User installs from /plugins (or the strategy marketplace).
4. User grants requested capabilities.
5. Runtime activates the pack under those scopes.
6. Update or revoke anytime — revoke drops grants immediately.

Bots and agents

Bot and agent packs register hooks into the agent runtime (ClawBot / agent config). Tools they expose must map to granted capabilities — the same pattern as MCP tool registration.

Strategies

Strategy packs use the existing commerce path: seller onboarding, Stripe, trials, and downloads under /strategies/marketplace. Plugins is the umbrella discovery surface; strategy remains the live billing product type today.

UI packs & dashboard control

Packs can rearrange the whole user desk — theme tokens, layout slots, widget order, and panels — under ui:* and dashboard:* capabilities.

• Tokens — background, ink, accent, radius, density.
• Slots — topbar, primary, rail, research pane, secondary, footer, widget/panel lists.
• Safe apply — CSS variables + data attributes only; no script injection into trading chrome.

Hard protections (never grantable)

No capability unlocks usage metering, billing, credentials, or auth. The mediated client denies these paths even if a pack asks:

• Compute Unit quota, burn rate, overages
• Feature usage / product analytics
• Invoices, subscriptions, Stripe customer data
• Broker vault keys, MCP service tokens, session cookies
• Admin / internal / webhook endpoints
• Protected widgets: cu_meter, usage_panel, billing_summary, vault_keys, …

import {
  assertPathAllowed,
  listProtectedResources,
  sanitizeWidgetList,
} from '@alphonce/plugins'

assertPathAllowed('/api/billing/history')
// → { ok: false, reason: '…protected (usage, billing…)' }

sanitizeWidgetList(['chart', 'cu_meter', 'holdings'])
// → ['chart', 'holdings']  // cu_meter stripped

Analytics plugins (PluginHost)

Strategy workspace analytics plugins run in a sandboxed iframe + Worker. Your function receives input and returns data only:

// input: { predicted, real, strategy }
const s = input.real.length ? input.real : input.predicted;
if (!s.length) return { note: 'No curve to measure.' };
let peak = s[0].v, worst = 0;
for (const p of s) {
  if (p.v > peak) peak = p.v;
  const d = (peak - p.v) / peak;
  if (d > worst) worst = d;
}
return {
  metrics: [{ label: 'Max drawdown', value: (worst * 100).toFixed(2) + '%' }]
};

Open the Plugins panel in the Strategy workspace to try starters.

Authoring checklist

• Request least privilege — drop unused capabilities.
• Never hide execute scopes or spoof Alphonce chrome.
• UI packs: contrast, mobile, reduced motion; keep trading CTAs reachable.
• Analytics: no network, no HTML, finish under the timeout.
• Document what the pack does in plain language for the install screen.