Skip to content

About

Agent-native execution transport layer

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

EasyNet Axon

The execution contract for governed Operators across runtimes.

Axon provides product-neutral invocation, authority/admission semantics, bounded execution lifecycles and verifiable receipt facts. It is the protocol, canonical Runtime model, native bridge and cross-language SDK foundation used by EasyNet.

The first product use case

EasyNet's product entry is turn a local function into an operation a teammate or agent can call. The first useful result is one real remote invocation. The architecture behind that path is a distributed Operator runtime, described as an Execution Fabric for Heterogeneous Data Environments. Existing catalogs can supply context when the operation acts on data.

For example, generating a Singapore revenue report may require operations over orders, refunds and currency rates held in different systems. The data owner publishes approved business operations; a caller discovers and invokes them without reconstructing every provider's execution interface. Resource access, business definitions and output restrictions remain explicit product concerns.

This is the target product workflow, not a claim that this repository ships a complete data execution product or those integrations today.

Caller / Agent
      | discover approved operations (EasyNet product)
      v
Operator + concrete resource/provider bindings
      | descriptor-bound Invocation (Axon)
      v
Runtime admission → provider execution → terminal outcome
                                      → receipt facts

Operator vocabulary

An Operator is one named, versioned callable operation with a declared input/output contract. SQL, functions, CLI commands, APIs and jobs can supply its implementation. A provider or package can expose multiple Operators. Stateful and stateless implementations are both valid.

Current public APIs still use Ability identifiers. AbilityTarget, AbilityDescriptor, AbilityDescriptorRef and /ability/ addresses below are real v1 names. Operator is the new framing; this documentation change does not introduce a second target kind, rename SDK methods or change signed identities. See the Operator contract and migration sequence.

Responsibilities

Layer Responsibility
EasyNet product Operation discovery, resource bindings, execution policy and outcome views
EasyNet Runtime Product deployment, provider integration, routing and orchestration
Axon Generic addressing, descriptor-bound Invocation, canonical admission/verification, bounded lifecycle and receipt facts
Provider Execute against concrete resources and enforce provider-side access/output constraints
Caller or Agent Choose operations and interpret results using business definitions

A catalog result is not permission to execute. Admission must validate the exact call under current authority. Resource-bound execution can avoid moving raw datasets into a central engine; outputs, logs and exports still need explicit controls. A signed Receipt attests recorded facts, not arbitrary computation correctness or absence of PII.

Ecosystem

Repository Role
EasyNet-Axon Protocol, canonical runtime, native bridge and language SDKs
EasyNet Product backend, operation discovery and execution console
EasyNet-Cli Device Runtime, daemon, product SDK, CLI, EAL and integrations
EasyRemote Python callable adaptation, packaging and resident provider host

EAL remains downstream orchestration that lowers work to child Invocations. Its existing name, syntax and package coordinates are unchanged. Agent planning and memory are outside Axon's execution contract.

Protocol Definition

Protocol

Axon defines the current product-neutral contract for resource naming, invocation semantics, content envelopes, signed admission/receipts, terminal states, streaming, and large-payload transfer.

The current wire surface is intentionally small: Invocation exposes Invoke, InvokeStream, and InvokeBidi; PayloadTransfer exposes UploadPayload, DownloadPayload, GetPayloadMeta, and DeletePayload.

Protocol Guarantees

Guarantee Meaning
Addressable Every routable identity has a canonical URA
Decidable Every operation terminates in a known state
Provable Signed admission and terminal outcomes contain verifiable proof facts
Resumable Event replay and configured persistent recovery have explicit bounds; stream-factory reopen does not guarantee exactly-once delivery
Bounded All concurrency knobs are finite; 0 means server maximum, not unbounded

Resource Namespace

URA Resource Managed by
easynet:///r/<realm>/agent/<agent-id> Runtime identity Identity
easynet:///r/<realm>/ability/<ability-id> Ability Descriptor/provider binding
easynet:///r/<realm>/resource/invocation/<invocation-id> Invocation Invocation
easynet:///r/<realm>/resource/stream/<session-id> Stream session Stream
easynet:///r/<realm>/resource/<owner-id>/payload/<payload-id> Large payload PayloadTransfer

Execution Modes

Mode Semantics RPC
SYNC Blocking request-response Invoke
SERVER_STREAM Progressive result chunks InvokeStream
BIDI_STREAM Bidirectional realtime session InvokeBidi

Async submit/watch, batch, and fan-out are not current Axon RPCs. Products may express them as explicit Abilities or caller-side composition.

Provider Boundary

Axon describes executable work without describing the product that provides it:

Generic runtime concept Ownership
AbilityDescriptor Immutable contract identity, schemas, and execution modes owned by Axon.
Provider implementation Runtime-local executable evidence registered behind the descriptor.
Provider binding Explicit association of one descriptor with one implementation inside a runtime.
BidiSession Bounded bidirectional session lifecycle, flow control, cancellation, and terminal closure.

MCP, A2A, audio, voice, remote control, tool adapters, and product federation are downstream provider or product capabilities. Their owners translate product requests into descriptor-bound Invocations and, when needed, register a provider implementation or consume BidiSession. Canonical Axon SDKs do not export their product protocol types, lifecycle helpers, catalogs, or presets.

Content Contract

Every protocol-crossing payload (input, output, stream chunk) uses ContentEnvelope with explicit MIME type, encoding, and optional schema.

Large payloads are referenced by PayloadRef (easynet:///r/<realm>/resource/<owner-id>/payload/<payload-id>) and carry full content metadata plus integrity digest.

Security Contract

The current protocol carries signed Invocation material, exact authority bindings, replay/idempotency inputs, signed receipt checkpoints, and content encryption representations. The canonical Runtime owns admission and verification semantics.

EncryptedPayload and ContentEnvelope.encryption describe ciphertext on the wire. Axon v1 does not currently expose an Identity/session-key negotiation service; key custody, negotiation, mTLS, and product trust policy are supplied by the consuming Runtime and deployment. The message schema alone is not an end-to-end confidentiality guarantee.

Performance and Resilience Contract

Primitive Current purpose
Priority Request priority hint carried by Envelope; the host maps it to bounded local policy
InvocationState Accepted -> Admitted -> Dispatched -> Running -> one terminal outcome
InvocationReceipt Signed admission and terminal checkpoints on signed paths
InvokeStream / InvokeBidi Explicit stream direction and terminal closure
PayloadTransfer Chunked upload/download, integrity metadata, and offset resume

Repository Structure

  • document/
    • Operator contract, current product framing, concepts, plans, and RFC documents.
  • core/proto/axon/v1/
    • Protocol contracts and service definitions.
  • core/runtime-rs/
    • Transport-only Rust client and native Dendrite bridge.
  • sdk/rust/
    • Canonical LocalRuntime, admission, receipt, lifecycle, and verifier authority.
  • sdk/
    • Language SDK packages (Go/Node/Python/Java/React/Swift).
  • packaging/
    • Protocol, SDK, and native transport build and release scripts.

Auto-versioning (via tide)

  • Root VERSION file holds the current project version coordinate from tide mark --local-only.
  • packaging/release/sync_versions.sh owns the existing manifest inventory.
  • Verify without mutation: bash packaging/release/sync_versions.sh --check.
  • Release preparation captures one Tide coordinate and passes it explicitly to ./scripts/update-project-version.sh <version>.

Documentation Index

  • PROJECT_STRUCTURE.md — Repository structure contract, migration rules, and required paths.
  • document/concepts/INVOCATION_STATE_MACHINE.md — Current Invocation state model.
  • document/concepts/INVOCATION_LIFECYCLE_ACROSS_PROCESSES.md — Cross-process lifecycle.
  • Operator contract — callable operation, binding and evidence boundaries.
  • Product framing — data use case, positioning and validation.
  • Migration sequence — public API and cross-repository work.
  • document/rfcs/ — Current protocol RFCs and amendments.
  • packaging/release/check_project_structure.sh — Automated project-structure guard for local/CI validation.
  • core/proto/axon/v1/*.proto (generic protocol files):
    • types.proto: core protocol types, addressing, execution semantics, content envelope, state enums.
    • invoke.proto: unary, server-stream, and bidi Invocation plus receipts.
    • transfer.proto: chunked payload upload/download, metadata query, garbage collection.

Product protocols such as voice and remote desktop are owned and versioned by their EasyNet-Cli ability/plugin packages. Axon carries their canonical invocations and receipts without compiling product lifecycle types.

Platform-aware SDK Packaging

CI builds SDK packs per native target. Release targets:

Target Extension SDK Pack
aarch64-apple-darwin .dylib sdk-packs-aarch64-apple-darwin.tar.gz
x86_64-apple-darwin .dylib sdk-packs-x86_64-apple-darwin.tar.gz
aarch64-apple-ios .a sdk-packs-aarch64-apple-ios.tar.gz
x86_64-apple-ios .a sdk-packs-x86_64-apple-ios.tar.gz
x86_64-unknown-linux-gnu .so sdk-packs-x86_64-unknown-linux-gnu.tar.gz
aarch64-unknown-linux-gnu .so sdk-packs-aarch64-unknown-linux-gnu.tar.gz
aarch64-linux-android .so sdk-packs-aarch64-linux-android.tar.gz
x86_64-pc-windows-msvc .dll sdk-packs-x86_64-pc-windows-msvc.tar.gz

Each pack contains dist/sdk-packs/<version>/ with language directories (python/, node/, react/, go/, java/, swift/, rust/) plus native/ and runtime/.

Cross-language distribution:

  • Python: PyPI hosts all target wheels; pip install auto-selects platform.
  • Node/React: npm publishes Linux x86_64; other targets via SDK pack extraction.
  • Go: go get easynet.run/axon/sdk/go; native alignment via SDK pack.
  • Java: Maven Central source artifact; target-native via SDK pack.
  • Swift: SPM from tag (macOS); iOS via aarch64-apple-ios / x86_64-apple-ios pack.
  • Rust: target-compiled in consumer build; EASYNET_DENDRITE_BRIDGE_LIB for explicit path injection.

Environment variables for cross-target/CI workflows:

  • SDK_TARGET, SDK_LIB_EXT, SKIP_NATIVE_BUILD, SDK_VERSION
  • EASYNET_DENDRITE_BRIDGE_PLATFORM=ios|android|linux|windows|macos
  • EASYNET_DENDRITE_BRIDGE_LIB=/abs/path/to/libaxon_dendrite_bridge.*
  • EASYNET_DENDRITE_BRIDGE_HOME=<pack-root>
  • EASYNET_DENDRITE_BRIDGE_SOURCE=local

SDK Runtime Lifecycle Surface

The base Dendrite Bridge surface is available in all six language SDKs. Node heartbeat renewal is no longer an SDK-owned node_agent loop: membership lifecycle belongs to the runtime/control plane, while SDKs own transport reconnect helpers and stream-factory retry wrappers.

Surface Rust Python Go Node Java Swift
Dendrite Bridge ✅ ✅ ✅ ✅ ✅ ✅
Automatic bridge reconnect driver ✅ ✅ ✅ ✅ Not provided Not provided
stream_resume (stream factory w/ transparent reopen) ✅ ✅ ✅ ✅ ✅ ✅

See the stream reopen evidence and test commands for implementation links, executed coverage and limits of this support table.

Java and Swift expose transport-error classification and backoff utilities for caller-owned reconnect loops; their options do not start an automatic bridge worker. Their stream wrappers independently reopen a caller-supplied source factory. See reconnect and stream evidence for implementation links and the scope of executed tests.

Contract for SDKs with automatic bridge reconnect drivers:

  • Reconnect backoff is bounded and monotonic; language facades expose explicit caps instead of unbounded retry loops.
  • Reconnect hooks run after the bridge is reopened so callers can re-register application resources without owning node membership.
  • Transport-looking failures trigger reconnect; validation and policy errors are returned unchanged.

stream_resume currently documents that exactly-once delivery across a reconnect is not guaranteed — reconnected streams restart from the factory, so consumers must layer idempotency keys at the downstream provider call site.

Canonical Runtime Delivery Boundary

  • LocalRuntime admission, replay/idempotency, provider registration, lifecycle, receipts, and verification semantics in sdk/rust/.
  • Unary Invoke, server-stream InvokeStream, and bidi InvokeBidi.
  • Explicit child-invocation causality and receipt anchors in the canonical model.
  • Large-payload upload/download, metadata, deletion, and offset resume.
  • Native Dendrite bridge plus cross-language SDK and conformance surfaces.

Product integrations, including MCP, A2A, audio/voice, remote control, tool adapters, and federation membership or discovery APIs, are not Axon delivery surfaces. They are implemented and versioned by downstream providers and products over the generic runtime model above.

License

Apache-2.0 — see LICENSE.

This repository is a deliberately bounded public release of the wider EasyNet research system. See Public Source Release Scope for what is published, what remains outside the distribution, and why releases are staged.

Author

Silan Hu · silan.hu@u.nus.edu

About

Agent-native execution transport layer

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages