LabAcacia.NPS.Core 1.0.0-alpha.16

English | 中文版

NPS .NET Reference Implementation

C# / .NET 10 reference implementation for the Neural Protocol Suite.

NuGet Packages

Open vs NPS Cloud

Quickstarts

Core Codec

using NPS.Core.Codecs;
using NPS.Core.Frames.Ncp;

var codec = NpsFrameCodec.CreateDefault();
var frame = new HelloFrame { Version = "1.0", NodeId = "urn:nps:demo", Capabilities = ["ncp"] };
var wire = codec.Encode(frame);
var header = codec.Peek(wire);
var decoded = codec.Decode(wire);

LabAcacia.NPS.Core uses MessagePack-CSharp for the built-in Tier-2 codec. Hosts that need a different binary codec can supply their own IFrameCodec implementation by constructing NpsFrameCodec with custom codec instances; the DI helper wires the default JSON + MessagePack pair.

Dependency Injection

using Microsoft.Extensions.DependencyInjection;
using NPS.Core.Extensions;

var services = new ServiceCollection()
    .AddNpsCore(options => options.EnableExtendedFrameHeader = true);

NIP Basic TrustFrame Validation

using NPS.NIP.Verification;

var result = TrustFrameValidator.Validate(trustFrame, new TrustFrameValidationContext
{
    TrustedGrantors = new HashSet<string> { "urn:nps:org-a:ca" },
    ExpectedGranteeCa = "urn:nps:org-b:ca",
    RequiredCapabilities = ["nwp:query"],
    TargetNodePath = "nwp://api.example.com/products",
});

Observability Without Kestrel

using NPS.Daemon.Observability.HealthChecks;

var health = HealthProbeRenderer.RenderHealthz();
var ready = await HealthProbeRenderer.RenderReadyzAsync(readinessProbes, cancellationToken);

ASP.NET Observability Endpoints

using NPS.Daemon.Observability;

builder.Services.AddNpsObservability();
app.MapNpsObservability();

Storage Packages

using NPS.NIP.Extensions;

services.AddNipCaWithSqlite(
    options => ConfigureCa(options),
    "Data Source=nip-ca.db");

services.AddNipCaWithPostgres(options =>
{
    ConfigureCa(options);
    options.ConnectionString = postgresConnectionString;
});

Bridge and Ingress Packages

LabAcacia.NPS.NWP.Bridge models both Bridge Node directions. BridgeNode and IBridgeDispatcher handle outbound NPS-to-external calls with built-in HTTP/HTTPS, gRPC JSON unary, MCP JSON-RPC, and A2A JSON-RPC dispatchers. McpServerBridge and A2aServerBridge expose local NPS actions to external MCP/A2A clients; inbound Bridge server dispatch requires a valid X-NWP-Agent NID plus a configured VerifyAgentAsync hook by default, binding the header to deployment NIP/capability policy. Request bodies and dispatches are bounded by MaxRequestBodyBytes and DispatchTimeoutMs; set RequireAuth = false only for local/dev-only ingress. The standalone LabAcacia.McpIngress, LabAcacia.A2aIngress, and LabAcacia.GrpcIngress compatibility edges are packed by the release workflow and become consumable after the NuGet publish step for that release.

using System.Text.Json;
using NPS.NWP.Bridge;
using NPS.NWP.Frames;

var registry = BridgeDispatcherRegistry.CreateDefault(new HttpClient());
var bridge = new BridgeNode(registry);

using var parameters = JsonDocument.Parse("""
{
  "bridge_target": {
    "protocol": "http",
    "endpoint": "https://api.example.test/run",
    "extras": {
      "method": "POST",
      "allowed_prefixes": [ "https://api.example.test/" ],
      "headers": { "x-agent": "nps" }
    }
  },
  "body": { "task": "sync" }
}
""");

var response = await bridge.DispatchAsync(new ActionFrame
{
    ActionId = "bridge.dispatch",
    Params = parameters.RootElement.Clone(),
    TimeoutMs = 5000
});

ASP.NET hosts can expose the same Bridge Node over NWP endpoints:

builder.Services.AddBridgeNode(
    options =>
    {
        options.NodeId = "bridge-1";
        options.PathPrefix = "/bridge";
    },
    dispatchers =>
    {
        // Optional: dispatchers.Register(new GrpcBridgeDispatcher(...));
    });

app.UseBridgeNode(); // GET /bridge/.nwm, GET /bridge/actions, POST /bridge/invoke

ASP.NET hosts can also expose local NPS actions as inbound MCP/A2A servers:

builder.Services.AddBridgeServer(options =>
{
    options.NodeId = "bridge-server-1";
    options.ServerName = "orders-bridge";
    options.PathPrefix = "/bridge-server";
    options.AddAction("orders.lookup", "Lookup an order by id.");
    options.DispatchAsync = async (frame, ct) =>
    {
        // Dispatch to your local Action Node / service boundary here.
        return await InvokeLocalActionAsync(frame, ct);
    };
});

app.UseBridgeServer();
// POST /bridge-server/mcp  (MCP tools/list + tools/call, JSON-RPC or SSE)
// POST /bridge-server/a2a  (A2A tasks/send)
// GET  /bridge-server/.well-known/agent.json

The hosted Bridge Node uses the named HttpClient nps-bridge; configure it through IHttpClientFactory when you need custom timeout, proxy, TLS, or retry policy:

builder.Services.AddHttpClient(BridgeServiceExtensions.HttpClientName, client =>
{
    client.Timeout = TimeSpan.FromSeconds(30);
});

Bridge dispatchers reject private and loopback endpoint hosts by default (reject_private=true). Set reject_private=false only for trusted local development targets.

Native NCP and Revocation

Native-mode NCP listeners can require an authenticated stream before the NPS/1.0\n preamble is read. Use the hook to install SslStream for TLS/mTLS:

var server = new NcpServer(port, NpsFrameCodec.CreateDefault(), new NcpServerOptions
{
    RequireAuthenticatedStream = true,
    HandshakeReadTimeout = TimeSpan.FromSeconds(10),
    MaxHelloPayload = 16 * 1024,
    AuthenticateStreamAsync = async (_, stream, ct) =>
    {
        var tls = new SslStream(stream, leaveInnerStreamOpen: false);
        await tls.AuthenticateAsServerAsync(serverOptions, ct);
        return tls;
    }
});

NipIdentVerifier supports static CRLs, live callbacks, CA stores, and OCSP. OCSP transport failures fail closed by default; set OcspFailOpen=true only when the host policy explicitly accepts that risk.

var verifier = new NipIdentVerifier(new NipVerifierOptions
{
    TrustedIssuers = trustedIssuers,
    RevocationStore = await SqliteNipCaStore.OpenAsync("Data Source=nip-ca.db"),
    RevocationCheck = (frame, ct) => ValueTask.FromResult<NipIdentVerifyResult?>(null),
    OcspUrl = "https://ca.example.test/v1/agents"
}, httpClientFactory);

Remote NIP CA Client

using NPS.NIP.Client;

httpClient.BaseAddress = new Uri("https://ca.example.test/");
var ca = new NipCaClient(httpClient);
var discovery = await ca.GetDiscoveryAsync(cancellationToken);
var issued = await ca.RegisterAgentAsync(new NipCaRegisterRequest(
    Identifier: "agent-1",
    PubKey: publicKeyBase64Url,
    Capabilities: ["nwp:query"],
    ScopeJson: "{}"),
    bearerToken,
    cancellationToken);

Native NWP Serving

using NPS.Core.Codecs;
using NPS.Core.Ncp;
using NPS.NWP.Native;

var nativeNode = new NwpNativeNodeServer(
    NpsFrameCodec.CreateDefault(),
    new NwpNativeNodeOptions { MemoryOptions = memoryOptions, ActionOptions = actionOptions },
    memoryProvider,
    actionProvider);

await nativeNode.ServeAsync(ncpSession, cancellationToken);

Conformance Manifests

using NPS.Conformance;

var manifest = NpsConformanceManifest.Create(
    NpsConformanceProfiles.NodeL1,
    iutName: "my-node",
    iutVersion: "0.1.0",
    iutNid: "urn:nps:node:example.test:node-1",
    peerName: "nps-dotnet-reference",
    peerVersion: "1.0.0-alpha.16",
    results: caseResults);

var validation = NpsConformanceValidator.Validate(manifest);

Build

dotnet build NPS.sln

Test

dotnet test

Status

Active development (v1.0.0-alpha.16). 696 tests passing.

Alpha.15 highlights: official llm.complete Action/Caps/Stream DTO contracts; typed frame payload helpers for CapsFrame, StreamFrame, async task results, and ErrorFrame.Details; Bridge bridge_target canonical wire shape aligned on extras; warning-clean .NET package family with SourceLink symbols; native NCP TLS hook and bounded Hello reads; live NIP revocation checks and signed CRL artifacts; NipCaClient; NwpNativeNodeServer; built-in Bridge dispatchers for HTTP/HTTPS, gRPC JSON unary, MCP JSON-RPC, and A2A JSON-RPC; transport-neutral observability renderers; LabAcacia.NPS.Conformance; loopback dev stack.