What Is the acn-protocol Package in Magnitude? RPC Contracts and Service Boundaries

The acn-protocol package serves as the canonical wire-level contract that governs how the Magnitude SDK communicates with the Agent Control Node (ACN) daemon, defining typed RPC boundaries, shared Effect schemas, and service facades while remaining isolated from direct UI client imports.

The acn-protocol package in the magnitudedev/magnitude repository establishes the foundational communication layer between the Magnitude SDK and the background ACN daemon. It codifies the exact message formats, service interfaces, and recovery policies required for type-safe, resilient remote procedure calls. By isolating these low-level concerns behind a versioned contract, the package enables independent evolution of client SDKs and daemon implementations without breaking cross-version compatibility.

Defining the RPC Surface with AcnRpc

At the heart of the package lies the AcnRpc adapter, which decorates Effect-Query operations with recovery policies and transforms them into callable RPC endpoints. Located in packages/acn-protocol/src/boundary/rpc.ts at lines 15-33, this adapter allows the SDK to invoke remote functions on the ACN daemon while ensuring that transient failures are handled according to predefined resilience strategies.

The adapter effectively bridges the gap between local Effect computations and network-bound operations. When the SDK initiates a call, the AcnRpc layer serializes the request, applies transport-level recovery policies, and deserializes responses back into typed Effect structures that the client code can consume safely.

Exposing Typed Service Boundaries

The package declares every public ACN service—such as Sessions, Projects, Models, and Display—within dedicated boundary files. These service definitions are then centrally re-exported from packages/acn-protocol/src/boundary/index.ts at lines 1-18, creating a clean separation between interface and implementation.

This boundary pattern ensures that both the SDK client and the ACN daemon share identical type definitions for all callable operations. When you import Sessions or Projects from the package, you are importing the typed contract that both sides of the connection must honor, eliminating drift between client expectations and server capabilities.

Providing Shared Effect Schemas

All data structures that cross the JSON wire boundary are modeled using Effect Schemas located in packages/acn-protocol/src/schemas/*. These schemas govern the serialization and deserialization of complex domain objects including model state, session definitions, project files, and onboarding data.

For example, packages/acn-protocol/src/schemas/model-state.ts defines the exact shape and validation rules for AI model configurations passed between processes. By using Effect's schema system, the package guarantees deterministic encoding and decoding, catching serialization mismatches at the type level before they reach runtime.

Architectural Isolation from UI Clients

According to AGENTS.md at lines 12-18, the acn-protocol package is explicitly designed to remain invisible to UI client code. Instead of importing directly from @magnitudedev/acn-protocol, client applications must consume these capabilities through @magnitudedev/client-common or @magnitudedev/sdk.

This layering invariant keeps the public API surface stable while allowing the protocol to evolve internally. The SDK acts as a protective facade, exposing only high-level workflows to client code while managing the low-level RPC details internally.

Implementing the ACN Protocol Contract

Calling Remote ACN Services from the SDK

To interact with the daemon, you initialize the transport layer and invoke service methods through the AcnRpc adapter:

import { AcnRpc } from "@magnitudedev/acn-protocol"
import { Sessions } from "@magnitudedev/acn-protocol"
import { DaemonSpawner } from "@magnitudedev/sdk"

// Spawn the daemon process (handled by the SDK)
const daemon = await DaemonSpawner.start()

// Obtain an RPC client that uses the AcnRpc adapter
const rpc = AcnRpc(daemon.transport)

// Use the generated service façade
const sessionInfo = await Sessions.getSessionInfo(rpc, {
  sessionId: "abc123"
})

// `sessionInfo` is typed according to the schema in
// `src/schemas/session.ts`

This pattern ensures that sessionInfo returns a value strictly typed according to the schema defined in src/schemas/session.ts, with all wire-format concerns handled transparently by the protocol layer.

Implementing ACN Service Handlers in the Daemon

When building a custom ACN daemon, you implement the service contracts defined in the protocol package:

import { Sessions } from "@magnitudedev/acn-protocol"
import { Effect } from "effect"

export const SessionsImpl = {
  getSessionInfo: (sessionId) =>
    Effect.succeed({ /* …session data shaped by src/schemas/session.ts… */ })
}

The daemon implementation must return Effect values that conform to the exact input/output types specified in the boundary definitions, ensuring runtime compatibility with SDK clients.

Validating Wire Data with Effect Schemas

For low-level validation of raw payloads before processing, you can invoke the schema decoders directly:

import { ModelState } from "@magnitudedev/acn-protocol"

const raw = JSON.parse(receivedPayload)
const validated = ModelState.decode(raw) // throws if payload does not match schema

This approach leverages Effect's decoding mechanisms to enforce the contracts defined in packages/acn-protocol/src/schemas/*, failing fast on malformed data before it propagates through the system.

Summary

• The acn-protocol package acts as the authoritative wire-level contract between the Magnitude SDK and the ACN daemon, located in the magnitudedev/magnitude repository.
• AcnRpc adapter in packages/acn-protocol/src/boundary/rpc.ts decorates Effect-Query operations with recovery policies and exposes them as callable RPC endpoints.
• Service boundaries in packages/acn-protocol/src/boundary/index.ts export typed facades for Sessions, Projects, Models, and other ACN services that both client and daemon share.
• Effect Schemas in packages/acn-protocol/src/schemas/* provide deterministic serialization guarantees for all data crossing the process boundary.
• Design constraint documented in AGENTS.md prevents direct UI client imports, forcing access through the SDK layer to maintain API stability.

Frequently Asked Questions

What is the primary purpose of the acn-protocol package in Magnitude?

The package defines the canonical wire-level contract that governs communication between the Magnitude SDK and the ACN daemon. It specifies the RPC surface, serialization schemas, and service boundaries required for type-safe inter-process communication, effectively serving as the trusted interface specification that both sides of the system implement.

Should client applications import acn-protocol directly?

No. According to the design documentation in AGENTS.md at lines 12-18, client applications must not import from @magnitudedev/acn-protocol directly. Instead, they should consume functionality through @magnitudedev/sdk or @magnitudedev/client-common, which provide stable public APIs while shielding client code from protocol-level changes.

How does acn-protocol ensure type safety across process boundaries?

The package uses Effect Schemas defined in packages/acn-protocol/src/schemas/* to validate and serialize all data crossing the JSON wire boundary. Combined with the AcnRpc adapter in packages/acn-protocol/src/boundary/rpc.ts, these schemas guarantee that messages conform to expected shapes at both transmission and receipt, catching type mismatches before they cause runtime failures.

Which services are exposed through the acn-protocol package?

The package exports typed boundaries for core ACN services including Sessions, Projects, Models, and Display, all re-exported from packages/acn-protocol/src/boundary/index.ts. Each service façade defines the exact method signatures and payload structures that the SDK can invoke and that the daemon must implement.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}