Skip to content

System Bundles and Atoms

JarvisCore integrations are built from atoms: small, typed Python functions that perform one provider action. The runtime loads shipped atoms into a versioned FunctionRegistry, exposes qualifying atoms as tools, records their execution evidence, and can register a proven replacement when an atom's source is genuinely defective.

A system bundle is generated registry metadata and code-generation context for the atoms associated with one provider. It is not a long-running tool server and it does not hold credentials.

flowchart LR
    Task["Agent task"] --> Search["Registry-first lookup"]
    Search -->|"verified or golden match"| Tool["Typed atom tool"]
    Search -->|"no suitable match"| Generate["Generate candidate code"]
    Generate --> Validate["Validate and execute in sandbox"]
    Validate -->|"successful evidence"| Register["Register immutable version"]
    Register --> Tool
    Tool --> Proxy["Nexus call boundary"]
    Proxy --> Provider["External provider API"]
    Provider --> Evidence["Result and execution evidence"]
    Evidence --> Registry["Update reliability stage"]

The atom contract

An atom is one provider call with a signature that becomes its tool schema. A current atom has:

  • a {system}_{verb}_{object} function name;
  • an async def entry point;
  • typed parameters and a dict result;
  • a docstring describing the action and linking to provider documentation;
  • provider access through nexus_call() rather than a token parameter;
  • a module-level ATOM_POLICY describing effects and idempotency.
jarviscore/integrations/atoms/slack/slack_send_message.py
ATOM_POLICY = {
    "effect": "notify",
    "approval": "never",
    "idempotency_fields": ["channel", "text"],
    "consequence": "Posts one message to the selected Slack channel.",
}


async def slack_send_message(
    channel: str,
    text: str,
    thread_ts: str | None = None,
) -> dict:
    """Send a message through the Slack API."""
    payload = {"channel": channel, "text": text}
    if thread_ts:
        payload["thread_ts"] = thread_ts

    response = await nexus_call(
        "POST",
        "https://slack.com/api/chat.postMessage",
        headers={"Content-Type": "application/json"},
        json=payload,
    )
    if not response["ok"]:
        return {"success": False, "error": response["body"]}
    return {"success": True, "data": response["json"]}

The exact response shape can preserve provider-native information. The durable contract is that the function returns structured data and reports provider failure honestly; an HTTP status alone is not a business decision.

Effect policy

ATOM_POLICY lets the runtime reason about side effects before execution.

Field Allowed values Meaning
effect read, write, notify, destructive The external effect class
approval never, required Whether the action needs explicit human approval
idempotency_fields Function parameter names Inputs that identify one intended mutation
consequence Short description The real-world change produced by the atom

write, notify, and destructive atoms require idempotency fields and a consequence. Destructive atoms require approval. An atom that performs HTTP DELETE must declare a destructive policy. An atom that performs HTTP POST, PUT, or PATCH must declare its policy explicitly, because many provider APIs use POST for searches and queries: the declaration, not the HTTP method, says whether the call changes anything. Every shipped atom carries one.

Atom modules are declarative: at module level they hold only imports, constant assignments, and function or class definitions, with no calls in decorators, defaults, annotations, or base classes. Reading an atom therefore never runs provider code.

The contract is checked from Python syntax by jarviscore.execution.atom_contract.read_contract(). Invalid source is not offered to agents as a callable capability.

Credentials stay outside the atom

Atoms do not accept raw credential parameters and do not retrieve provider tokens. nexus_call() sends the provider intent through NexusCallProxy, where the runtime validates the host, resolves the connection, injects authentication, and performs the HTTP call.

sequenceDiagram
    participant Atom
    participant Proxy as NexusCallProxy
    participant Auth as Authentication manager
    participant Provider

    Atom->>Proxy: nexus_call(method, URL, request data)
    Note over Atom,Proxy: No raw token in atom or agent context
    Proxy->>Auth: resolve scoped connection
    Auth-->>Proxy: request strategy with credential
    Proxy->>Provider: authenticated HTTP request
    Provider-->>Proxy: response
    Proxy-->>Atom: structured response without credential

The proxy may refresh an expired OAuth connection and retry once. Authentication, permission, rate-limit, and truthful provider refusals are not evidence that atom source should be rewritten.

Catalog ownership

Shipped atoms are loaded into a fresh registry at startup. Existing registries receive missing shipped atoms without discarding local execution history or valid local repairs. That seeding behavior belongs to the runtime model; the provider and atom inventory does not.

Use the installed package for machine-readable inventory:

jarviscore atom list
jarviscore atom list --bundle hubspot

Use the Integrations guide for the human-readable provider and atom catalog. Keeping that list in one place prevents concept pages from drifting when integrations are added or renamed.

Shipped external atoms are hand-audited against provider documentation and seed as verified. Newly generated functions enter as candidate and need successful execution evidence before promotion.

The FunctionRegistry

FunctionRegistry owns immutable source versions and current metadata. A registration writes a new atom version instead of mutating the prior source. Metadata includes:

  • provider system, capabilities, description, and tags;
  • current version, source path, and SHA-256 hash;
  • execution count, success/failure counts, and average duration;
  • current reliability stage and consecutive-success streak;
  • repair lineage such as repair_of_version;
  • whether the source is managed by the shipped catalog.

The local registry can publish an index to Redis for fleet discovery and copy source/metadata to configured blob storage. Those persistence details are runtime implementation; agents interact with the registry through tool discovery rather than reading storage paths.

Reliability stages

Stage Entry condition Failure behavior
candidate New generated function without execution proof Remains candidate; streak resets
verified Shipped audited atom or at least one consecutive successful execution Demotes to candidate; streak resets
golden At least five consecutive successful executions Demotes to verified; streak resets

Stages answer "does this work now?" rather than "did this ever work?" A failure records its type, resets the success streak, and demotes one level. Credential boundary failures are excluded because the atom did not execute.

How AutoAgent finds and executes atoms

CoderSubAgent follows a registry-first path:

  1. Normalize the task intent and call check_registry.
  2. Rank matching atom metadata. Despite its historical method name, semantic_search() is lexical ranking; provider authority comes from the task/capability context, not substring matching.
  3. Offer a qualifying verified or golden atom as a typed tool.
  4. Execute the atom through the sandbox and Nexus boundary.
  5. Record successful or failed execution evidence in the registry.

If no suitable atom exists, the Coder can write candidate code, validate it, execute it, and register it only after successful execution. Registration without a successful candidate_id is rejected.

When a provider has registered atoms, generated code reaches that provider only through them: a direct nexus_call to the provider is refused unless the code is the atom being proven. A missing operation becomes a new atom rather than a one-off script.

stateDiagram-v2
    [*] --> RegistryLookup
    RegistryLookup --> ExecuteKnown: verified or golden match
    RegistryLookup --> WriteCandidate: no suitable match
    WriteCandidate --> Validate
    Validate --> WriteCandidate: contract or syntax failure
    Validate --> ExecuteCandidate: valid candidate
    ExecuteCandidate --> Register: successful real execution
    ExecuteCandidate --> Repair: eligible code failure
    Repair --> ExecuteCandidate: corrected candidate
    Register --> Verified
    ExecuteKnown --> Evidence
    Verified --> Evidence
    Evidence --> [*]

Repair, extension, and new atoms are evidence-bound

The Coder maintains the catalog during a run, so developers do not hand-maintain atoms. Every change is proven by a real execution before registration.

Change Opens when Rules
Repair The atom failed in the current run Same function identity; proven against the failed invocation
Extension The atom ran in this run, and the Coder states the gap it cannot cover Read atoms only; same policy; every existing parameter kept; new parameters have defaults; proven against the observed call
New atom No registered atom covers the operation Read atoms only; name not already registered; proven by one stated call (write_code(atom=..., call=...))

Atoms with real-world effects are never extended or created by proof, because proving them would perform the effect without approval.

The Coder must inspect the exact current source/version before submitting a replacement. Registration rejects stale changes when the current atom version changed after work began. A successful replacement records repair_of_version and the observed failure or stated gap while retaining all prior immutable source versions.

What a system bundle is

FunctionRegistry.create_system_bundle(system_name) generates a {System}Capabilities class from that system's verified and golden functions. The class describes available methods and capabilities and is cached as Python source. prepare_code_with_bundle() can prepend it to generated code as code-generation context.

The generated methods intentionally raise NotImplementedError; a bundle is not a credential-bearing SDK client and application code should not instantiate it to call a provider. During normal AutoAgent execution, the Coder offers validated atoms as native tools, and custom generated provider code uses nexus_call().

Relationship to MCP

MCP and JarvisCore atoms solve adjacent problems at different boundaries.

Concern MCP server JarvisCore atom
Unit Tool exposed by a separate server Typed Python provider function in the registry
Discovery Client/server protocol discovery Registry metadata and capability-aware runtime context
Execution RPC to the MCP server Sandbox/native tool execution through runtime boundaries
Credentials Defined by each MCP deployment Nexus resolves credentials outside agent-visible code
Evidence Server-specific Registry stage, execution stats, immutable versions, and repair lineage

JarvisCore 1.11 does not ship a first-party MCP client. An application may wrap an existing MCP client behind a CustomAgent, but that is application code, not a built-in compatibility promise. Keep working MCP servers when they already solve your tool boundary; use atoms when you want JarvisCore's registry, execution evidence, Nexus boundary, and repair lifecycle.

  • Integrations: browse installed systems and atom names.
  • Testing Atoms: validate custom atom source and connected behavior.
  • Nexus: understand the credential boundary.
  • AutoAgent: see how the Kernel offers and executes tools.