What Are the Responsibilities of the ICN (Inference Communication Node) in Magnitude?

The Inference Communication Node (ICN) in Magnitude is a private, local-inference runtime that handles binary resolution, process supervision, model lifecycle management, and hardware calibration—serving as the sole authority for all native inference concerns within an Agent Coordination Node (ACN).

The ICN is implemented by the @magnitudedev/icn package and lives inside an ACN process. According to the Magniude source code, it maintains strict ownership boundaries: ACN consumes the ICN through a generated client, but the ICN never exposes public APIs for hardware or model loading directly. This design isolates inference complexity from higher-level orchestration policies.

---

Core Responsibilities of the ICN

The ICN's duties are specified in design/icn/lifecycle.md and implemented across the @magnitudedev/icn package. Here are the ten primary responsibilities:

Binary Resolution and Verification

The ICN resolves a release-matched installation path for the magnitude‑inference binary, verifies its build identity and API version, and ensures the executable belongs to the declared installation. This prevents version skew between the ACN caller and the inference runtime.

Process Supervision

The ICN spawns exactly one child process running magnitude‑inference serve within an Effect scope. It obtains a race-free loopback address and owns the entire child process lifetime. This ownership boundary is strict—no external process management is permitted.

Generated Client Exposure

The ICN constructs the IcnClient from the OpenAPI contract in @magnitudedev/icn-protocol and exposes a scoped client whose streams preserve their response lifetime. ACN code accesses this through the IcnProcess service tag.

Hardware Discovery and Calibration

The ICN discovers host inference hardware, runs calibration workers, and publishes calibrated hardware facts. These facts inform model placement decisions upstream in ACN.

Model Catalog and Acquisition

The ICN owns four related duties:

• Catalog — reviewed model metadata
• Discovery — inventory of installed models
• Catalog-installation — downloading and verifying packages
• Assessment — running native planning pipelines to compute memory, performance, and capability footprints

Model Instance Lifecycle

The ICN admits a model-free server, then manages model instance creation, replacement, stopping, and eviction. It handles leases, exposes progress via ModelInstancesSnapshot, and ensures inference requests hold valid leases before streaming begins.

Health and Readiness

The ICN publishes /health and readiness records containing process identity, API version, and hardware calibration status. ACN uses these signals to determine when the ICN can accept work.

Graceful Shutdown

On SIGTERM, the ICN initiates graceful shutdown with a ≤ 1 s deadline, then escalates to SIGKILL if needed. It closes all streams, cancels pending work, and cleans up the child process. This is implemented in the shutdown handler referenced by ACN.

Observability

The ICN emits structured logs and tracing spans for process start, exit, health checks, model loading, and shutdown. It maintains a bounded diagnostic tail for debugging without unbounded memory growth.

Boundary Enforcement

The ICN never exposes public listeners or client-side APIs for hardware, inventory, or native model loading. ACN is the sole consumer of the IcnClient. This isolation prevents unauthorized direct access to inference resources.

---

How ACN Interacts with ICN Responsibilities

The following snippets from packages/acn/src/icn.ts and packages/acn/src/server.ts demonstrate how ACN exercises ICN responsibilities through the generated client.

Creating the ICN Provider

// packages/acn/src/server.ts — bootstrap ICN into ACN service layer
import { makeIcnProvider } from "@magnitudedev/icn";

const acnServices = Layer.provideMerge(
  // ...other ACN layers...
  makeIcnProvider(),          // ← Injects scoped IcnClient
);

Loading a Model and Obtaining a Lease

// ACN service code acquiring a model instance
import { IcnProcess } from "@magnitudedev/icn";

const loadModel = Effect.gen(function* () {
  const icn = yield* IcnProcess;               // Scoped client from provider
  const lease = yield* icn.loadModel({         // Native model load
    modelId: "local/gguf/phi-2",
    // optional quantization, context length, etc.
  });
  // `lease` resolves when the inference stream completes
  return lease;
});

Graceful Shutdown

// ACN requesting ICN shutdown during its own teardown
import { IcnProcess } from "@magnitudedev/icn";

const shutdown = Effect.scoped(Effect.gen(function* () {
  const icn = yield* IcnProcess;
  // Sends SIGTERM, waits grace period, then SIGKILL if needed
  yield* icn.shutdown;
}));

---

Key Source Files for ICN Responsibilities

File	Relevance
design/icn/lifecycle.md	Complete specification of ICN responsibilities, ownership model, and state machine
packages/acn/src/server.ts	ACN bootstrap code that calls makeIcnProvider()
packages/acn/src/icn.ts	Implementation of makeIcnProvider, IcnProcess, and lifetime management
packages/icn-protocol/src/generated/	OpenAPI-generated IcnClient types and operations
design/model-management/instance-lifecycle.md	Model instance state machine that ICN implements
info/inference/parity.md	ICN usage for parity testing against reference implementations

---

Summary

• The ICN is the private, process-scoped inference authority inside each ACN, implemented by @magnitudedev/icn.
• It handles binary verification, process supervision, hardware calibration, model catalog/discovery/assessment, and instance lifecycle management.
• ACN consumes ICN capabilities through a generated IcnClient obtained via makeIcnProvider() and the IcnProcess service tag.
• Strict boundary enforcement prevents external access to hardware and model APIs—ACN is the sole client.
• Graceful shutdown, health/readiness signaling, and observability ensure production-hardened operation.

---

Frequently Asked Questions

What is the relationship between ICN and ACN in Magnitude?

The ICN runs as a child process inside an ACN. ACN is the public-facing orchestrator that handles user sessions, cloud routing, and policy decisions. It delegates all native inference work—model loading, hardware discovery, request execution—to the ICN through a private generated client. This separation keeps the inference runtime isolated and version-locked to the ACN that spawned it.

How does the ICN handle model loading and leasing?

The ICN manages a model instance lifecycle: it admits a model-free server, then creates instances on demand. Each load request returns a lease—an Effect that represents the right to stream inference from that instance. The ICN evicts or replaces instances based on memory pressure and policy, publishing state via ModelInstancesSnapshot. Inference requests must hold valid leases before streaming begins.

Is the ICN accessible outside the ACN process?

No. The ICN deliberately enforces a strict boundary: it binds to a race-free loopback address and never exposes public listeners. The @magnitudedev/icn-protocol client is only distributed within the ACN package graph. External consumers must route through ACN's public API, which proxies or policy-gates all inference requests.

What happens when an ICN receives a shutdown signal?

The ICN implements a two-phase shutdown: on SIGTERM, it stops accepting new work, waits up to 1 second for active streams to complete, then escalates to SIGKILL if the process has not exited. All streams are closed, pending work is cancelled, and the magnitude‑inference child process is reaped. ACN triggers this during its own teardown sequence.

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