@agent-mc/plugin-sdk
TypeScript types, interfaces, and validators for building Agent Mission Control plugins
Overview
This package provides the type definitions and manifest validators for Agent Mission Control (AMC) plugins. It is a dev dependency for plugin projects — it supplies TypeScript interfaces for the sandboxed PluginContext your backend code receives, the AgentMC browser bridge your UI code uses, and a Zod-powered manifest validator for build-time checks.
Install
npm install @agent-mc/plugin-sdk --save-dev
Usage
Backend types
import type { PluginActivate, PluginContext } from '@agent-mc/plugin-sdk'
const activate: PluginActivate = (ctx) => {
return {
async onEnable() {
const data = await ctx.storage.get('config')
ctx.log.info('Plugin enabled', data)
},
async onShutdown() {
ctx.log.info('Goodbye')
},
}
}
export default activate
Browser bridge types
import type { AgentMC } from '@agent-mc/plugin-sdk/browser'
declare global {
interface Window { AgentMC: AgentMC }
}
const settings = await window.AgentMC.settings.getAll()
Manifest validation
import { validateManifest } from '@agent-mc/plugin-sdk/validators'
const result = validateManifest(manifest)
if (!result.valid) {
console.error(result.errors)
}
PluginContext API
Every backend plugin receives a PluginContext with these sandboxed capabilities:
| Capability | Interface | Permission | Description |
|---|---|---|---|
storage | PluginStorage | storage | Key-value store (get, set, delete, list) |
db | PluginDb | storage | SQLite collections (insert, query, getById, update, delete) |
fs | PluginFs | storage | Sandboxed filesystem (readFile, writeFile, exists, listDir) |
sessions | PluginSessions | sessions | Create and manage Claude Code sessions |
ai | PluginAi | ai | Direct AI text generation (generateMessage, generateTitle) |
http | PluginHttp | network | Outbound HTTP requests (fetch) |
cron | PluginCron | cron | Scheduled recurring tasks |
cli | PluginCli | cli | HTTP endpoints on AMC's control server |
toast | PluginToast | notifications* | In-app toasts and OS notifications |
sidebar | PluginSidebar | — | Badge count and navigation items |
settings | PluginSettings | — | Read plugin settings (getAll, get) |
log | PluginLogger | — | Scoped logging (info, warn, error, debug) |
events | PluginEvents | — | Pub/sub event system (emit, on) |
* toast.show() is always available; only toast.notify() (OS-level) requires the notifications permission.
Permissions
Declare in manifest.json — AMC shows these at install and enforces at runtime:
{
"permissions": ["storage", "network", "ai"]
}
| Permission | Grants |
|---|---|
storage | ctx.storage, ctx.db, ctx.fs |
sessions | ctx.sessions |
ai | ctx.ai |
network | ctx.http |
cron | ctx.cron |
cli | ctx.cli |
notifications | ctx.toast.notify() |
rss | Access to AMC's built-in RSS feed data |
Exports
This package provides five entry points:
| Import path | What it provides |
|---|---|
@agent-mc/plugin-sdk | All TypeScript types + validateManifest() + manifestSchema + checkCommandTables() |
@agent-mc/plugin-sdk/browser | AgentMC browser bridge type for UI plugins |
@agent-mc/plugin-sdk/validators | Zod manifest schema and validation function |
@agent-mc/plugin-sdk/commands | createCommandChannel (backend) and createCommandClient (panel): a private command channel agents cannot write to |
@agent-mc/plugin-sdk/testing | createTestContext, createRpcDouble and describeForgedRowsAreInert for plugin tests |
Backend Lifecycle
interface PluginBackend {
onEnable?(): Promise<void> | void
onDisable?(): Promise<void> | void
onSettingsChanged?(settings: Record<string, unknown>): Promise<void> | void
onAppReady?(): Promise<void> | void
onShutdown?(): Promise<void> | void
}
Documentation
Full guides, API reference, and examples: Omniscio Plugin SDK Docs
- Getting Started — scaffold your first plugin
- Manifest Reference — full manifest.json spec
- Permissions — what each permission grants
- Panel Commands — send commands from your panel to your backend safely
- API Reference — all 20 capability interfaces