Atom Packs

​

The capability model

import { defineAtomPack, SDK_COMPATIBILITY_RANGE } from '@monad/sdk-atom';

export default defineAtomPack({
  manifest: {
    name: 'my-atom-pack',
    version: '1.0.0',
    sdkVersion: SDK_COMPATIBILITY_RANGE,
    atoms: ['channel'], // ← declared, auditable, enforced
  },
  channels: [myChannel],
});

• Declared = audited + enforced. An atom pack that declares ['channel'] cannot registerProvider — that throws UndeclaredAtomError at load. An atom pack gets a capability only after the user audits and consents to it (default-deny).
• JS-registered atoms (channel / command / message-type / provider / hook / sandbox / agent-adapter / workplace-experience) are enforced in-process via the gated AtomPackContext — must be listed in atoms[]. The full enum is atomKindSchema in packages/protocol/src/atom-pack.ts.
• File-based atoms (skill / mcp / locale) bypass the JS gate entirely. The daemon scans for them on disk; file presence = self-declaration. No atoms[] entry needed (optional if you want to advertise them in the consent UI).
• Resource capabilities (network, fs, llm) are audit-only today — in-process JS can’t be stopped from calling fetch/node:fs. True runtime enforcement requires the out-of-process adapter host (a later phase). Don’t assume a declared resource cap is sandboxed yet.

​

Bundling multiple atoms in one pack

import { defineAtomPack, SDK_COMPATIBILITY_RANGE } from '@monad/sdk-atom';

export default defineAtomPack({
  manifest: {
    name: 'acme',
    version: '1.0.0',
    sdkVersion: SDK_COMPATIBILITY_RANGE,
    atoms: ['channel', 'command', 'provider', 'message-type'], // declare ALL kinds used
  },
  channels: [acmeChannel],
  commands: [acmePing],
  providers: [acmeProvider],
  messageTypes: [acmeBadge],
});

​

Conflict & failure semantics

• message-type is namespaced under the pack id (<packId>:<type>) — cross-pack types never collide; registering the same id twice within a pack throws.
• locale is pick-one, not merged: only one pack is active per locale tag (user-installed wins, then atom packs sorted by folder name, then builtin). The active pack replaces others wholesale; keys it doesn’t translate fall back to en via the normal fallback chain. Locale files live in <packDir>/locales/<lng>/<namespace>.json (one file per namespace); user-managed packs in ~/.monad/atoms/locales/.
• mcp servers are registered by name (mcpServers.<name> in the JSON config). Each atom pack ships an optional mcp.json; user-managed configs go in ~/.monad/atoms/mcp/. Three transport variants: stdio (external CLI), http (remote SSE/streamable-HTTP), and bundled (deferred — packed server binary, TBD).
• hook is additive: every hook for an event runs; there is no identifier and no dedup.

Rollout status. provider hard-unique, locale file-based pick-one (user-dir > atom packs sorted > builtin), mcp file-based (daemon scans <packDir>/mcp.json + ~/.monad/atoms/mcp/*.json at startup), skill file-based (daemon scans <packDir>/skills/*/ + ~/.monad/atoms/skills/*/), channel namespace-coexist + pin, command namespace-coexist + pin (built-ins reserved), message-type namespacing, and hook additivity are all live. Remaining: conflict-surfacing UI for skill bare-name collisions; bundled MCP server variant (cross-language, deferred).

• Same pack, duplicate id is always an authoring bug → that pack aborts on the duplicate; atoms registered before it stay, later ones are skipped.
• The user pin is the one resolution override across Family 1 + locale: unset → first-wins; set → always resolves to the pinned pack. Collisions are surfaced in the UI (global settings + the in-use agent view) so the user can pin/rename/disable rather than silently accepting first-wins.
• Partial failure is not rolled back. A multi-atom pack registers atom-by-atom; if one throws, the already-registered siblings remain and the failure is reported per-pack via onError. Packs are independent — one failing pack never blocks another.

​

Why tools aren’t atoms

​

Hot install

export default defineAtomPack({
  manifest: { /* … */ },
  channels: [myChannel],
  deactivate: () => clearInterval(pollTimer)
});

​

Authoring a channel

import { defineChannel } from '@monad/sdk-atom';

export const myChannel = defineChannel({
  type: 'whatsapp', // any string — ChannelType is open, not a fixed enum
  name: 'WhatsApp',
  capabilities: { edit: false, typing: true, threads: false, maxMessageChars: 4096, markdown: false },
  envVars: [{ name: 'WHATSAPP_TOKEN', description: 'API token', required: true, secret: true }],
  create(ctx) {
    // ctx: { onMessage, log, config: {id,type,label}, secrets, signal }
    return {
      type: 'whatsapp',
      capabilities: { edit: false, typing: true, threads: false, maxMessageChars: 4096, markdown: false },
      async connect() {
        /* open your socket / start your poll loop; push inbound via ctx.onMessage(...) */
      },
      async disconnect() {},
      async send(chatId, content, opts) {
        /* deliver to the platform */ return { ref: 'platform-msg-id', chatId };
      },
    };
  },
});

• chatType: 'dm' (default if omitted), 'group', or 'channel'.
• mentionedSelf: true when the bot was @mentioned or the message replies to the bot. In a group the core stays silent unless mentionedSelf (or a slash command) — see groupPolicy.requireMention.

• Long-poll / dial-out WebSocket / TCP (no public URL): telegram.ts (getUpdates), discord.ts / qq.ts (Gateway WS), slack.ts (Socket Mode WS), irc.ts (raw TCP via Bun.connect).
• Inbound webhook (HTTP listener): line.ts, whatsapp.ts, twilio.ts, feishu.ts, wecom.ts, teams.ts, google-chat.ts, imessage.ts (BlueBubbles), plus the generic webhook.ts. These share _http-inbound.ts — a helper that owns the Bun.serve listener, GET URL-verification handshakes, raw-body HMAC signature checks (hmacSha256Hex/Base64, hmacSha1Base64, timingSafeEqual), and fan-out to ctx.onMessage; the adapter supplies verify/parse + its own outbound send().
• Local IMAP poll: email.ts (raw IMAP over TLS + SMTP, hand-rolled, plain-text/no-IDLE).
• Child process: signal.ts (drives signal-cli jsonRpc via Bun.spawn — Signal has no bot API).

​

Authoring a model provider

import { defineProvider, defineAtomPack, SDK_COMPATIBILITY_RANGE } from '@monad/sdk-atom';

const myProvider = defineProvider({
  type: 'my-vendor', // open string; also the Provider.type stored in config.json
  // Self-describing metadata — the daemon assembles the provider catalog (UI/CLI picker, base-url
  // hint, key placeholder, extra fields) from every registered provider's descriptor.
  descriptor: { type: 'my-vendor', label: 'My Vendor', strategy: 'native', keyPlaceholder: 'mv-…' },
  // The only required method. The gateway resolves a profile → provider + credential and calls it;
  // yield Monad-native chunks (text / reasoning / tool-call / usage). Throw on a request error so
  // the gateway can fail over to the next credential/model in the chain.
  async *stream(call) {
    // call: { modelId, messages, tools?, params, provider, credential, signal?, fetch? }
    yield { type: 'text', token: 'hello' };
    yield { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } };
  },
  // Optional: complete() (else the gateway aggregates stream), generateImage/generateSpeech,
  // listModels (powers the connection test + model picker; attach `price` for native pricing),
  // countTokens (native exact count; best-effort, resolve undefined on error).
});

export default defineAtomPack({
  manifest: {
    name: 'my-vendor',
    version: '1.0.0',
    sdkVersion: SDK_COMPATIBILITY_RANGE,
    atoms: ['provider'],
  },
  providers: [myProvider],
});

​

Testing offline

import { createChannelTestHarness } from '@monad/sdk-atom';

const h = createChannelTestHarness(myChannel, { secrets: { token: 'x' } });
// drive your platform mock, then assert what the adapter normalized:
expect(h.received[0]?.text).toBe('hello');
// assert outbound hit your platform mock by spying on it; h.dispose() aborts the signal.

​

Packaging & distribution

• GitHub repository: github:owner/repo[@ref] or a GitHub URL. The repository must contain the prebuilt Atom Pack at its root (or at the selected URL subdirectory); private repos use the token stored directly in config.json.atomRegistries.github.
• Local development directory: local:/abs/path (a prebuilt Atom Pack directory).
• Drop-in: place <name>/{atom-pack.json, dist/atom-pack.js} in ~/.monad/atoms/packs/ directly.

​

Authoring file-based atoms (skill / mcp / locale)

​

Skill

my-atom-pack/
└── skills/
    └── code-reviewer/
        ├── SKILL.md          ← required — skill instructions for the agent
        ├── FORMS.md          ← optional companion doc
        └── scripts/
            └── lint.sh       ← optional scripts referenced in SKILL.md

​

MCP server

{
  "mcpServers": {
    "github-tools": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
    },
    "my-remote": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

• stdio: command + args + optional env. Launched as a child process.
• http: url pointing to an SSE or streamable-HTTP MCP endpoint.

​

Locale pack

my-atom-pack/
└── locales/
    └── zh-TW/
        ├── cmd.json          ← flat key-value for cmd.* keys
        └── web.json          ← flat key-value for web.* keys

​

Security model (summary)

• Narrow ChannelContext — defense in depth: an atom pack’s channel adapter can’t reach the agent’s tools or internals; it does platform I/O only.
• Capability declaration + user consent + runtime enforcement (least privilege).
• The consented manifest is authoritative, not the bundle. The runtime gate is built from the on-disk atom-pack.json atoms — the artifact the user audited and consented to at install — not from the manifest the bundle embeds in its own defineAtomPack(). A bundle can self-declare any set; trusting it would let an installed pack register atom kinds the user never approved. At discovery the loader also refuses a bundle whose embedded atoms exceed the consented set (a drift signal — reinstall to re-consent). Drop-ins with no atoms in atom-pack.json are gated default-deny (empty grant).
• Load order is stable (atom-pack dirs sorted by folder name), so cross-pack first-wins conflict resolution is reproducible across machines rather than filesystem-order-dependent.
• SHA/integrity pinning (rug-pull guard) and sdkVersion checks on install.
• Channel platform sender ids are used only for rate limits and conversation routing; every channel session still sends high-risk tools through the oversight gate.