@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
});

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

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.

License

Business Source License 1.1 — See LICENSE for details.