@aura-labs-ai/scout

Scout SDK for AURA — Build buying agents that participate in agentic commerce.

What is a Scout?

A Scout is a user-sovereign buying agent in the AURA ecosystem. Scouts:

• Express purchase intent in natural language
• Discover products through AURA Core's neutral broker
• Evaluate offers against user-defined constraints
• Commit to transactions while preserving privacy

Installation

npm install @aura-labs-ai/scout

Quick Start

import { createScout } from '@aura-labs-ai/scout';

// Zero-config — auto-generates Ed25519 identity and registers with Core
const scout = createScout();
await scout.ready();

// Express purchase intent with constraints
const session = await scout.intent('I need 500 widgets', {
  maxBudget: 50000,
  deliveryBy: new Date('2026-03-01'),
});

// Wait for offers (polling)
const offers = await session.waitForOffers();

// Commit to best offer that meets constraints
if (session.bestOffer) {
  const tx = await session.commit(session.bestOffer.id);
  console.log('Transaction:', tx.id);
}

CLI Tool

The SDK includes a CLI for testing:

# Interactive mode (zero-config, uses Ed25519 keys)
npx @aura-labs-ai/scout

# Single intent mode
npx @aura-labs-ai/scout --intent "I need office supplies" --max-budget 500

HTTPS Enforcement: The CLI requires HTTPS for all Core API connections. Plaintext HTTP is only permitted for localhost and 127.0.0.1 during local development. Use --core-url https://... or set AURA_CORE_URL with an HTTPS URL.

Constraint Engine

Define hard constraints (must be met) and soft preferences (influence ranking):

const session = await scout.intent('Buy enterprise software licenses', {
  // Hard constraints - offers that don't meet these are filtered out
  maxBudget: 100000,
  deliveryBy: new Date('2026-06-01'),
  hardConstraints: [
    { field: 'compliance', operator: 'eq', value: 'SOC2' },
  ],

  // Soft preferences - influence offer scoring
  softPreferences: [
    { field: 'support', operator: 'eq', value: '24/7', weight: 10 },
    { field: 'rating', operator: 'gte', value: 4.5, weight: 5 },
  ],
});

Constraint Operators

Only the following operators are accepted. Unknown operators are rejected (fail-closed) to prevent constraint bypass:

| Operator | Description | |----------|-------------| | eq | Equal to | | ne | Not equal to | | gt | Greater than | | gte | Greater than or equal | | lt | Less than | | lte | Less than or equal | | contains | String contains | | in | Value in array |

API Reference

createScout(config)

Create a new Scout instance. Authentication is handled via Ed25519 public key registration — no API keys required.

const scout = createScout({
  coreUrl: 'https://aura-labsai-production.up.railway.app', // optional, defaults to production
  timeout: 30000, // optional, ms
  storage: customStorageAdapter, // optional, defaults to in-memory
  constraints: {}, // optional, default constraints
  principalId: 'prn_01HXYZ...', // required — registered principal ID
  capacity: 'agent_for_principal', // optional, defaults to 'agent_for_principal'
});

// Initialize and register with AURA Core (idempotent)
await scout.ready();

Principal registration: Before creating a Scout, register the principal (legal entity) via POST /v1/principals. The principalId links this agent to the accountable entity. See Protocol Spec Section 3.1 for details.

Capacity options:

• agent_for_principal — Agent acts on behalf of the declared principal (default)
• principal_direct — The principal is operating directly (no separate agent entity)
• platform_delegated — A platform operates the agent on behalf of multiple principals

scout.ping()

Read-only connectivity check. Verifies Core is reachable and its dependencies are healthy. Does not require ready() — works on a freshly created instance. No auth headers sent.

const health = await scout.ping();

// When Core is healthy:
// { status: 'ok', core: { status: 'ready', checks: { database: {...}, redis: {...} } }, latency_ms: 42, timestamp: '...' }

// When Core is alive but degraded (503):
// { status: 'degraded', core: { status: 'not_ready', checks: {...} }, latency_ms: 105, timestamp: '...' }

// When Core is unreachable:
// { status: 'error', code: 'CORE_UNREACHABLE', message: '...', latency_ms: 30000, timestamp: '...' }

// When Core times out:
// { status: 'error', code: 'CORE_TIMEOUT', message: '...', latency_ms: 30000, timestamp: '...' }

Activity events: ping.success (Core responded), ping.failed (network error or timeout). Summary counters available via scout.activity.getSummary().ping.

scout.intent(text, options)

Create a commerce session with purchase intent.

const session = await scout.intent('I want to buy...', {
  maxBudget: number,
  deliveryBy: Date,
  hardConstraints: Constraint[],
  softPreferences: Constraint[],
});

session.waitForOffers(options)

Poll for offers until available.

const offers = await session.waitForOffers({
  timeout: 30000, // max wait time
  interval: 2000, // poll interval
});

session.commit(offerId)

Commit to an offer.

const transaction = await session.commit(offer.id);

session.validOffers

Get offers that meet all hard constraints.

session.bestOffer

Get highest-scoring valid offer.

Error Handling

import { ScoutError, AuthenticationError, SessionError } from '@aura-labs-ai/scout';

try {
  await scout.intent('...');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof SessionError) {
    console.log('Session error:', error.message);
  }
}

Key Storage

Ed25519 private keys are persisted across restarts using pluggable storage adapters from @aura-labs-ai/sdk-common. The createStorage() factory auto-detects the best adapter for the current platform:

| Platform | Adapter | Details | |----------|---------|---------| | macOS | KeychainStorage | Hardware-backed encryption at rest via Secure Enclave on Apple Silicon. Uses the security CLI — zero native dependencies. | | Linux / Windows | FileStorage | JSON file at ~/.aura/keys.json with 0600 permissions (owner read/write only). | | Testing | MemoryStorage | In-memory, ephemeral. No persistence. |

import { createScout, createStorage } from '@aura-labs-ai/scout';

// Auto-detect (recommended)
const scout = createScout({ storage: createStorage() });

// Force file-based storage
const scout = createScout({ storage: createStorage({ type: 'file' }) });

// Force Keychain (macOS only — throws on other platforms)
const scout = createScout({ storage: createStorage({ type: 'keychain' }) });

// Custom file path
const scout = createScout({ storage: createStorage({ type: 'file', path: '/custom/keys.json' }) });

Override the default file path with the AURA_KEY_PATH environment variable.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | AURA_CORE_URL | Core API URL (optional) | https://aura-labsai-production.up.railway.app | | AURA_KEY_PATH | Custom path for file-based key storage | ~/.aura/keys.json |

Authentication

Scout uses Ed25519 public key cryptography for identity. When you call scout.ready():

1. An Ed25519 key pair is auto-generated (or loaded from storage)
2. The Scout registers with AURA Core via POST /agents/register using proof-of-possession (signed request)
3. Core assigns an agent ID, which is persisted for future sessions
4. All subsequent requests are signed with the private key for identity verification

No API keys or other credentials are required.

Protocol Modules (Phase B)

Scout SDK ships modules for the external commerce protocols AURA composes with. All sign with Ed25519 via Node's crypto.sign(null, data, key) API (NOT createSign('sha256') — Ed25519 does its own internal hashing and does not take a hash algorithm parameter).

| Module | Path | Purpose | |--------|------|---------| | AP2 (Google Agent Payments Protocol) | src/ap2/mandates.js | Intent → Cart → Payment mandate creation, signature verification, intent-coverage validation. | | TAP (Visa Trusted Agent Protocol) | src/tap/visa.js | Agent registration, request signing per HTTP Message Signatures, key rotation. | | MCP (Model Context Protocol) | src/mcp/client.js | Beacon discovery and protocol query. |

Test coverage:

node --test src/tests/ap2-mandates.test.js     # AP2 mandates: 20 tests
node --test src/tests/visa-tap.test.js         # Visa TAP: 21 tests
node --test src/tests/mcp-client.test.js       # MCP client: 18 tests

License

Business Source License 1.1 — See LICENSE for details.