molecule-ai-sdk

The Molecule AI SDK and contract SSOT. One repo, three things:

1. Two Python packages (published together under the distribution name molecule-ai-sdk in Molecule's publicly readable Gitea package registry; publishing remains authenticated, and the package is not on public PyPI):

   • molecule_external_workspace — write an agent that runs outside the platform's Docker network and joins a Molecule AI org from another machine. It registers with the platform, pulls secrets, sends heartbeats, discovers peers (A2A), delegates, and detects pause/delete. Public API: RemoteAgentClient, A2AServer.
   • molecule_plugin — build installable plugin directories (rules, skills in agentskills.io format, per-runtime install adaptors) + validators and the molecule-plugin CLI. (See Plugin authoring.)

2. contracts/ — the platform contract SSOT. The JSON-Schema (draft 2020-12) IDL for every cross-boundary contract in the platform, plus the cloud-provider YAML SSOT. This is the former molecule-contracts repo, folded in and archived here 2026-07-01. See Contracts.

3. gen/ — generated bindings. Go / TypeScript / Python types + constants emitted from contracts/ by tools/gen-*.mjs. Consumed by molecule-core and molecule-controlplane (Go, via go.moleculesai.app/sdk/gen/go/...), the storefront (TS), and the runtime (Python). Never hand-edited — a fresh regen must match what's committed (enforced by CI).

molecule-ai-sdk/
├── molecule_external_workspace/   # remote-agent client (RemoteAgentClient / A2AServer)
├── molecule_plugin/               # plugin-authoring SDK + validators + CLI
├── contracts/                     # JSON-Schema IDL SSOT + cloudproviders.yaml
│   ├── mcp/  plugin-manifest/  workspace-template/  org-template/
│   ├── catalog/                   # catalog-entry + marketplace-service (catalog/publish/install/entitlement)
│   ├── provision-request/  promote-request/  workspace-comms/
│   └── cloudproviders.yaml + cloudproviders.schema.json
├── gen/{go,ts,python}/            # generated bindings (DO NOT EDIT)
├── tools/gen-runtimes.mjs + gen-{go,ts,python}.mjs  # Node generators
├── molecule_plugin/templates/     # packaged skill/MCP/channel/trigger scaffolds
└── tests/

SDK release boundary: 0.6.0 is not published

This branch describes the unreleased 0.6.0 release candidate. The latest package in the Molecule Gitea registry is molecule-ai-sdk==0.5.5; there is no sdk-v0.6.0 tag or 0.6.0 wheel yet. Version 0.5.5 includes the plugin CLI and channel scaffold. 0.5.5 does not contain the native-channel retirement validator described below. An install from the registry therefore does not prove the 0.6.0 channel cutover.

Contributors validating the release candidate must use a reviewed, exact source commit and install that checkout with python -m pip install -e '.[test]'. Production consumers must remain on an immutable published version until the 0.6.0 tag, wheel, and release validation are complete.

Install

SDK_DOWNLOAD="$(mktemp -d)"
python -m pip download --no-deps --dest "$SDK_DOWNLOAD" \
  --index-url "https://git.moleculesai.app/api/packages/molecule-ai/pypi/simple" \
  molecule-ai-sdk==0.5.5
python -m pip install --index-url https://pypi.org/simple \
  "$SDK_DOWNLOAD"/molecule_ai_sdk-*.whl

The Gitea registry does not proxy public PyPI. Download only the private SDK wheel from Gitea, then install that local wheel while resolving its declared public dependencies from PyPI. Keeping retrieval in separate commands avoids both a broken sole-index install, dependency drift, and cross-index dependency confusion. Authenticate via ~/.netrc (or pip's keyring) — do not inline credentials in the URL.

Go consumers import the generated bindings via the vanity path (no PyPI needed):

import molcontracts "go.moleculesai.app/sdk/gen/go/molcontracts"

Contracts — the SSOT

Every contract is a pair under its contracts/<domain>/ directory:

• *.schema.json — the rules (JSON-Schema draft 2020-12): fields, types, required, enum, const pins, patterns. The enforceable definition.
• *.contract.json — one canonical instance that MUST validate against its sibling schema. It's the worked example, the CI anchor, and — for value-bearing contracts like mcp-plugin-delivery — the SSOT for the concrete values baked into gen/.

Direction: *.contract.json ──validate──▶ *.schema.json, and contracts/ ──codegen (tools/gen-*.mjs)──▶ gen/{go,ts,python}. Each domain directory under contracts/ carries its own README.md describing that surface.

Eight jobs back this under the strict all-required aggregator in .gitea/workflows/contracts-codegen-drift.yml: schema validation, codegen drift, cloud-provider and adapter/prompt/platform conformance, Go parity, and published binding parity. Regenerate locally after any contract edit and commit the result:

node tools/gen-runtimes.mjs
node tools/gen-go.mjs && node tools/gen-ts.mjs && node tools/gen-python.mjs

Remote agents — molecule_external_workspace

from molecule_external_workspace import RemoteAgentClient

client = RemoteAgentClient(
    platform_url="https://<org>.moleculesai.app",
    workspace_id="my-agent",
    # the auth token is minted on first register() and persisted client-side
)

The client wraps the workspace↔platform HTTP contract (register, pull secrets, heartbeat, state-poll, A2A proxy delivery, delegation, plugin install) — the same surface captured in contracts/workspace-comms/. A2AServer is the authenticated receive side for agent-to-agent messages and rejects traffic until registration provides a platform_inbound_secret. Before exposing it publicly, attach it to the client, register, require the returned secret, and only then start the listener.

Plugin authoring — molecule_plugin

A Molecule AI plugin is a directory that bundles rules, skills, and per-runtime install adaptors. Any plugin that conforms to the contract is installable on any Molecule AI workspace whose runtime the plugin supports.

Quick start

Create a validated scaffold directly from the installed wheel:

molecule-plugin init my-plugin --kind skill
cd my-plugin
molecule-plugin validate plugin .

Use --kind mcp for a dependency-free stdio MCP starter, --kind channel for a supervised provider bridge with a vendored, provider-neutral channel API v1 client, or --kind trigger for an autonomous scheduler. Names must be lowercase alphanumeric slugs with single hyphens. The initializer refuses path traversal and never overwrites an existing directory.

my-plugin/
├── .gitea/workflows/ci.yml  # generated repository CI
├── .gitignore
├── README.md
├── plugin.yaml              # name, version, runtimes, description
├── adapters/
│   ├── claude_code.py       # AgentskillsAdaptor entrypoint
│   └── codex.py
├── skills/my-plugin/
│   └── SKILL.md             # instructions injected into the system prompt
└── tests/test_scaffold.py   # generated scaffold smoke test

Validate:

from molecule_plugin import validate_manifest
errors = validate_manifest("my-plugin/plugin.yaml")
assert not errors, errors

CLI

molecule-plugin init my-skill-plugin --kind skill
molecule-plugin init my-mcp-plugin   --kind mcp
molecule-plugin init my-channel      --kind channel
molecule-plugin init my-scheduler    --kind trigger
molecule-plugin validate plugin    my-plugin/
molecule-plugin validate workspace workspace-configs-templates/claude-code-default/
molecule-plugin validate org       org-templates/molecule-dev/
molecule-plugin validate my-plugin/   # kind defaults to 'plugin'

# Channel and trigger repos pin a vendored copy of the public local-A2A client.
molecule-plugin channel-sdk check my-channel/
molecule-plugin channel-sdk sync  my-channel/  # intentional SDK upgrade

Exit code is 0 when valid, 1 when any errors are found — suitable for CI. Add -q / --quiet to suppress success lines and emit only errors. python -m molecule_plugin ... remains an equivalent invocation.

Manifest validation follows the canonical contracts/plugin-manifest/plugin-manifest.schema.json: name, version, and description are required; known contributes entries are shape-checked; unknown contribution points remain forward-compatible. The authoring validator requires every declared daemon to match the canonical name/command/args/ env/cwd shape, so a typo fails before publication. Runtime admission remains backward-compatible: an already-installed legacy manifest with a malformed daemon is skipped with a warning instead of bricking the workspace.

The following channel-cutover behavior is part of unreleased 0.6.0; it is not present in the published 0.5.5 package.

Channel integrations are kind: channel plugins in plugins[]; the retired native org-template channels key is rejected at the root, defaults, and every recursive workspace node with migration guidance. The schema and authoring validator match the reserved channels/defaults/workspaces/children field names case-insensitively in YAML and JSON-form documents. Validation also inspects every explicit duplicate structural-key occurrence before normal last-key-wins decoding, while preserving explicit-key precedence over YAML merge sources. Nested business mappings such as category_routing.channels remain valid. The public molecule_plugin.channel module owns the API v1 client contract: reserved runtime environment names, canonical A2A request construction, response parsing, and explicit unavailable/protocol/delivery-unknown failures. Generated channel scaffolds vendor that module byte-for-byte so their daemon does not import private runtime code. Generated pull-request CI validates the manifest, checks that the vendored client still matches its pinned SDK, and runs the scaffold tests. The SDK's own required PR suite also exercises a provider event through the generated bridge and a real authenticated Unix socket to an agent reply.

Programmatic equivalents:

from molecule_plugin import (
    send_channel_message,
    channel_message_response_text,
    validate_plugin,
    validate_workspace_template,
    validate_org_template,
)

Per-runtime adaptors — when to write a custom one

The default AgentskillsAdaptor handles the common shape: rules go into the runtime's memory file (CLAUDE.md), skill dirs go into /configs/skills/. That covers most plugins.

The adaptor records exact ownership under /configs/.molecule/plugin-ownership/. Uninstall removes only unchanged files, the exact marked memory block, and the plugin's exact settings contribution; pre-existing and user-modified content is preserved. Legacy installs without a record are a safe no-op. See docs/migrations/plugin-uninstall-ownership.md.

Write a custom adaptor when you need to:

• Register runtime tools dynamically — call ctx.register_tool(name, fn).
• Register runtime sub-agents — call ctx.register_subagent(name, spec).
• Write to a non-standard memory file — call ctx.append_to_memory(filename, content).

Minimum custom adaptor:

# adapters/codex.py
from molecule_plugin import InstallContext, InstallResult

class Adaptor:
    def __init__(self, plugin_name: str, runtime: str):
        self.plugin_name, self.runtime = plugin_name, runtime

    async def install(self, ctx: InstallContext) -> InstallResult:
        ctx.register_subagent("my-agent", {"prompt": "...", "tools": [...]})
        return InstallResult(plugin_name=self.plugin_name, runtime=self.runtime, source="plugin")

    async def uninstall(self, ctx: InstallContext) -> None:
        pass

Resolution order (understood by the platform)

For (plugin_name, runtime):

1. Platform registry — workspace-template/plugins_registry/<plugin>/<runtime>.py (curated; set by the Molecule AI team for quality-assured plugins).
2. Plugin-shipped — <plugin_root>/adapters/<runtime>.py (what this SDK helps you build).
3. Raw-drop fallback — copies plugin files into /configs/plugins/<name>/ and surfaces a warning; no tools are wired.

You generally ship for path #2. If your plugin becomes popular enough to be promoted to "default," the Molecule AI team PRs a copy of your adaptor into the platform registry (path #1) so it survives upstream breakage.

Runtime identifiers and official support

Runtime IDs are open, bounded, path-safe slugs defined by contracts/adapter/runtime-id.schema.json; third-party adapters are not blocked by a first-party allowlist. The separate official registry contains Claude Code, Codex, Hermes, and OpenClaw. Known aliases such as claude_code normalize to their canonical ID, while other valid IDs remain unchanged.

Build and test

pip install -e '.[test]'   # base packages + pytest-asyncio
pytest -q