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 defentry point; - typed parameters and a
dictresult; - a docstring describing the action and linking to provider documentation;
- provider access through
nexus_call()rather than a token parameter; - a module-level
ATOM_POLICYdescribing effects and idempotency.
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:
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:
- Normalize the task intent and call
check_registry. - 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. - Offer a qualifying verified or golden atom as a typed tool.
- Execute the atom through the sandbox and Nexus boundary.
- 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.
What to read next¶
- 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.