@nexusprotocol-ai/sdk

TypeScript runtime for publishing Nexus Protocol capabilities from a controlled backend gateway.

What it provides

• Capability registry and /.well-known/nexus-agent.json manifest generation.
• JSON Schema input validation before business code runs.
• Confirmation enforcement for all non-read capabilities by default.
• A2UI v1 builders for native, structured agent results.
• A small in-memory task store for local development and tests.

Example

import { a2ui, nexus } from "@nexusprotocol-ai/sdk";

export const app = nexus({
  name: "Atlas Operations",
  version: "0.1.0",
  gateway: "https://atlas.example.com/agent",
  authenticate: async (request) => getCurrentUser(request),
});

app.capability({
  id: "entities.search",
  title: "Search entity profiles",
  description: "Find profiles available to the current user.",
  risk: "read",
  inputSchema: {
    type: "object",
    properties: { query: { type: "string", minLength: 2 } },
    required: ["query"],
    additionalProperties: false,
  },
  handler: async (input, context) => {
    const rows = await searchEntities(input.query, context.identity);
    return {
      data: { count: rows.length },
      a2ui: a2ui.document("Entity profiles", [
        a2ui.status("success", `${rows.length} profiles found`),
        a2ui.table(["Name", "Type", "Status"], rows),
      ]),
    };
  },
});

Mount it in a fetch-compatible handler such as a Next.js route:

import { app } from "@/server/nexus";

export async function GET(request: Request) { return app.handle(request); }
export async function POST(request: Request) { return app.handle(request); }

The runtime serves GET /.well-known/nexus-agent.json and expects capability requests at POST /agent/capabilities/:id.

Local development

npm run build:sdk
npm run test:sdk

validateManifest(app.manifest()) is the programmatic base for the forthcoming nexus validate CLI command. It checks the published capability contract without executing a write capability.