Neura Relay SDK v0.1.3

Stable package for sending proposed actions to Neura Relay and reading Decision Receipts.

Status: stable SDK package for the npm latest release line.

Package identity:

@neurarelay/[email protected]

The public SDK path is the GitHub relay-action-card example, Relay Workspace sandbox proof, and this npm package. The SDK wraps the same direct Action Card to Decision Receipt path and keeps execution in your runtime.

Quick Start

From any Node 18+ project:

npm install @neurarelay/sdk

Send a proposed action to Relay and read the Decision Receipt:

import { createNeuraRelaySdk } from "@neurarelay/sdk";

const relay = createNeuraRelaySdk({
  baseUrl: "https://www.neurarelay.com"
});

const result = await relay.resolve.resolve({
  action_card: actionCard
});

const receipt = result.decision_receipt;

console.log(receipt?.decision);
console.log(receipt?.trace_ref);

Relay returns the decision and refs. Your runtime still owns execution.

Automatic Discovery

Use these URLs when an agent, crawler, evaluator, or developer needs the shortest machine-readable route into Neura Relay:

• Relay AI-readable summary: https://www.neurarelay.com/llms.txt
• Relay public Agent Card: https://www.neurarelay.com/.well-known/agent-card.json
• Relay first proof: https://www.neurarelay.com/developers/first-proof
• Public proof repo: https://github.com/neurarelay/relay-action-card

These are discovery surfaces only. They do not issue public production tokens, execute downstream actions, or claim provider approval.

Current private API contract anchor: protected-session POST /api/developer/resolve-action-card responses include private_developer_api.version = "0.2", private_developer_api.response_posture = "decision_receipt_validation_registry_ledger_trace_refs_only", stable refs, sanitized receipt explanation and route-pressure summaries, Registry-backed production-trust posture, and explicit no-execution, no-public-key, no-public-production-token, and no-private-payload flags.

Version 0.1.3 includes typed authority_context.source support for the Registry-backed delegated authority trust slice. This lets runtime consumers branch on registry_reference_packet versus developer_supplied_unverified after reading a Decision Receipt.

SDK v0.1.3 includes:

• createNeuraRelaySdk
• createResolveClient
• createPrivateDeveloperApiClient
• resolveActionCardWithPrivateDeveloperApi
• resolveActionCardForDeveloperRouting
• buildPrivateDeveloperActionRoutingDecision
• createRelayA2AClient
• fetchRelayA2AAgentCard
• sendActionCardThroughRelayA2A
• A2A aliases and extractors: discover, resolveActionCard, resolveActionCardThroughRelayA2A, getRelayA2ADecisionReceiptArtifactData, and getRelayA2AControlledRuntimeContract
• createRelayMcpClient
• listRelayMcpTools
• callRelayMcpTool
• resolveActionCardThroughRelayMcp
• governed case lifecycle helpers
• RelaySdkHttpError
• RelaySdkResponseShapeError
• dist/index.js ESM build output
• dist/index.d.ts declaration output
• package exports map
• subpath exports for ./a2a, ./mcp, ./resolve, ./private-developer-api, and ./governed-cases
• package examples for core Action Card, A2A Agent Card, protected A2A Action Card, and protected MCP resolve
• TypeScript-first Action Card example
• TypeScript-first delegated authority source inspection through DecisionReceiptAuthorityContextV01
• TypeScript-first private developer routing example with delegated authority trust posture
• TypeScript-first Authority Layer v1 readiness example
• TypeScript-first A2A Action Card example
• npm pack verification
• clean consumer install verification

Compatibility note: 0.1.3 keeps names such as privateDeveloper, private-developer-api, and ready_for_developer_owned_execution because they are published API names. Read them as the protected runtime path: Relay reviews the proposed action; your runtime owns execution.

The SDK mirrors the direct core path:

Action Card -> Relay -> Decision Receipt -> trace / ledger / Registry context

When delegated authority is present, the typed Decision Receipt authority context exposes:

receipt.authority_context?.source
// "registry_reference_packet" | "developer_supplied_unverified"

registry_reference_packet means Relay matched the delegated authority refs against a protected Registry Relay Reference Packet. developer_supplied_unverified means Relay preserved refs-only caller-supplied authority without claiming Registry-backed authority.

It also mirrors the verified public A2A discovery boundary: /.well-known/agent-card.json is public metadata, while /a2a remains protected execution only. The SDK A2A response type follows Relay's real task-shaped JSON-RPC result: kind: "task", completed task status, Decision Receipt artifact data, trace ref, transaction ref, registry-trust summary, controlled-runtime contract, refs-only payload posture, and runtime-owned downstream execution. The SDK does not issue public A2A tokens, public API keys, public production MCP tokens, token values, private payloads, or downstream execution commands.

Current Scope

Stable package support includes:

• aggregate SDK facade
• resolve flow
• protected-session private API response contract inspection
• private developer routing decision helper
• public Agent Card fetch
• protected A2A message/send Action Card wrapper
• controlled A2A runtime-contract and Decision Receipt artifact extractors in repository source
• protected MCP tools/list and tools/call wrappers
• protected MCP resolve_action_card wrapper
• governed case creation
• governed case retrieval
• evidence attachment
• proposal
• challenge
• approve
• block
• reopen
• close
• typed HTTP and response-shape errors

Public GitHub Example

Run the public GitHub example:

git clone https://github.com/neurarelay/relay-action-card.git
cd relay-action-card
npm install
npm run example:sdk

Source Repo Development

The commands in this section are for the Relay source repository, not for a normal npm consumer project.

Start Relay locally from the repo root:

npm run dev

Default local base URL:

http://localhost:3000

Local Package Build

From the Relay repo root:

npm run build:sdk
npm run verify:sdk-package-candidate

The package verifier runs npm pack, installs the generated tarball into a clean temporary consumer project, imports @neurarelay/sdk at runtime, and type-checks the declaration output.

The protected TypeScript A2A example ships in the package as examples/typescript-a2a-action-card.ts. It requires RELAY_A2A_ACCESS_TOKEN and reads the task artifact returned from protected message/send; it is not public token issuance or unprotected A2A execution.

The live npm publication verifier checks npm install metadata and a clean outside consumer install:

npm run verify:sdk-npm-publication

For manual local package inspection:

npm pack ./packages/sdk --pack-destination .sdk-pack

Then install the generated .tgz into a separate local test project.

Aggregate Usage

import { createNeuraRelaySdk } from "@neurarelay/sdk";

const neura = createNeuraRelaySdk({
  baseUrl: "https://www.neurarelay.com"
});

const resolution = await neura.resolve.resolve({
  action_card: {
    version: "0.1",
    agent: {
      id: "agent_support_reply_001",
      owner: "acme_support",
      capability: "customer_message_draft",
      capabilityVersion: "0.1.0"
    },
    proposedAction: {
      type: "send_message",
      summary: "Send a customer reply confirming that the document was received and will be reviewed today.",
      target: "customer_thread_123"
    },
    affectedObject: "customer_thread_123",
    context: {
      evidenceRefs: ["ticket_123", "uploaded_document_456"],
      ruleRefs: ["customer_reply_policy"],
      riskCategory: "customer_communication",
      requestedOutcome: "proceed_or_review"
    }
  }
});

console.log(resolution.decision_receipt?.decision);
console.log(resolution.decision_receipt?.trace_ref);

Protected Runtime Routing

The protected route returns a refs-only response and can be converted into a local runtime route. The privateDeveloper namespace remains the compatibility name.

const routing = await neura.privateDeveloper.resolveActionCardForRouting({
  version: "0.1",
  agent: {
    id: "agent_support_reply_001",
    owner: "acme_support",
    capability: "customer_message_draft",
    capabilityVersion: "0.1.0"
  },
  proposedAction: {
    type: "send_message",
    summary: "Send a customer follow-up email",
    target: "customer_thread_123"
  },
  context: {
    evidenceRefs: ["ticket_123"],
    ruleRefs: ["customer_reply_policy"],
    riskCategory: "customer_communication",
    requestedOutcome: "proceed_or_review"
  }
});

if (routing.route === "ready_for_developer_owned_execution") {
  // Your runtime may continue after honoring its own execution controls.
}

For delegated authority routing, inspect the trust posture before your system executes:

if (
  routing.production_trust.delegated_authority_source ===
    "registry_reference_packet" &&
  routing.production_trust.delegated_authority_status === "ready"
) {
  // Registry-backed delegated authority is ready for runtime-owned execution.
}

Routes:

• ready_for_developer_owned_execution means runtime-owned execution is ready
• hold_for_production_trust_review
• human_review
• revise
• stop
• hold

For the protected-session walkthrough, read the Relay repo's Private Developer API quickstart at docs/private-developer-api-quickstart.md. The public GitHub adoption repo also includes npm run example:sdk:authority-routing, which demonstrates the same ready/hold/review routing logic using public delegated-authority demo refs.

Authority Layer v1 Readiness

Protected private developer responses include authority_layer_v1, and the SDK can turn that contract into a readiness object:

const response = await neura.privateDeveloper.resolveActionCard(actionCard);
const readiness = buildAuthorityLayerV1DeveloperReadiness(response);

if (readiness.ready && response.decision_receipt?.decision === "proceed") {
  // Your runtime may continue after honoring its own execution controls.
}

The package example examples/typescript-authority-layer-v1.ts checks the v1 contract, scenario floor, closed boundary flags, and refs-only core path before returning a local routing posture.

A2A Usage

const agentCard = await neura.a2a.getAgentCard();

const a2aResponse = await neura.a2a.sendActionCard({
  version: "0.1",
  agent: {
    id: "agent_support_reply_001",
    owner: "acme_support",
    capability: "customer_message_draft",
    capabilityVersion: "0.1.0"
  },
  proposedAction: {
    type: "send_message",
    summary: "Send a customer follow-up email",
    target: "customer_thread_123"
  },
  context: {
    evidenceRefs: ["ticket_123"],
    ruleRefs: ["customer_reply_policy"],
    riskCategory: "customer_communication",
    requestedOutcome: "proceed_or_review"
  }
});

const task = a2aResponse.result;
const artifactData = getRelayA2ADecisionReceiptArtifactData(a2aResponse);
const runtimeContract = getRelayA2AControlledRuntimeContract(a2aResponse);

console.log(agentCard.skills.map((skill) => skill.id));
console.log(task?.status.state);
console.log(artifactData?.decision_receipt?.receipt_id);
console.log(artifactData?.trace_ref);
console.log(artifactData?.transaction_ref);
console.log(artifactData?.registry_trust?.posture);
console.log(runtimeContract?.version);

The A2A client sends JSON-RPC message/send to /a2a with browser credentials included by default. That endpoint is protected; unauthenticated clients should expect rejection. Repository source also supports caller-supplied idempotency keys and returns only a hashed idempotency.key_ref, not the raw key.

MCP Usage

const tools = await neura.mcp.listTools();

const mcpResponse = await neura.mcp.resolveActionCard({
  version: "0.1",
  agent: {
    id: "agent_support_reply_001",
    owner: "acme_support",
    capability: "customer_message_draft",
    capabilityVersion: "0.1.0"
  },
  proposedAction: {
    type: "send_message",
    summary: "Resolve through protected MCP before execution",
    target: "customer_thread_123"
  },
  context: {
    evidenceRefs: ["ticket_123"],
    ruleRefs: ["customer_reply_policy"],
    riskCategory: "customer_communication",
    requestedOutcome: "proceed_or_review"
  }
});

console.log(tools.result?.tools?.map((tool) => tool.name));
console.log(mcpResponse.result?.isError ?? false);

The MCP client calls protected /mcp. It requires Workspace sandbox access, controlled production access, or an equivalent authorized bearer credential. It does not issue tokens.

Package Examples

From the Relay source repo:

node packages/sdk/examples/core-action-card.mjs
tsx packages/sdk/examples/typescript-action-card.ts
tsx packages/sdk/examples/typescript-private-developer-routing.ts
tsx packages/sdk/examples/typescript-authority-layer-v1.ts
node packages/sdk/examples/a2a-agent-card.mjs
RELAY_A2A_ACCESS_TOKEN=<controlled_a2a_token> tsx packages/sdk/examples/typescript-a2a-action-card.ts
NEURA_RELAY_MCP_TOKEN=<workspace_sandbox_token> node packages/sdk/examples/mcp-protected-resolve.mjs

Production Action Card Example

const response = await fetch("https://www.neurarelay.com/api/resolve", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    action_card: {
      version: "0.1",
      agent: {
        id: "agent_support_reply_001",
        owner: "acme_support",
        capability: "customer_message_draft",
        capabilityVersion: "0.1.0"
      },
      proposedAction: {
        type: "send_message",
        summary: "Send a customer reply confirming that the document was received and will be reviewed today.",
        target: "customer_thread_123"
      },
      affectedObject: "customer_thread_123",
      context: {
        evidenceRefs: ["ticket_123", "uploaded_document_456"],
        ruleRefs: ["customer_reply_policy"],
        riskCategory: "customer_communication",
        requestedOutcome: "proceed_or_review"
      }
    }
  })
});

const result = await response.json();

console.log(result.decision_receipt.decision);
console.log(result.decision_receipt.trace_ref);
console.log(result.decision_receipt.recommended_next_step);

Boundary

This SDK does not introduce:

• public API-key issuance
• public production MCP token issuance
• public A2A token issuance
• unprotected A2A execution
• downstream execution
• private payload exposure
• external Registry submission
• Registry auto-approval

Your runtime still executes, revises, stops, or escalates the action after reading the Decision Receipt and production-trust context.