@aura-labs-ai/scout 0.2.0

package/README.md

@@ -0,0 +1,237 @@
+# @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
+
+```bash
+npm install @aura-labs-ai/scout
+```
+
+## Quick Start
+
+```javascript
+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:
+
+```bash
+# 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):
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+const offers = await session.waitForOffers({
+  timeout: 30000, // max wait time
+  interval: 2000, // poll interval
+});
+```
+
+### `session.commit(offerId)`
+
+Commit to an offer.
+
+```javascript
+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
+
+```javascript
+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. |
+
+```javascript
+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](LICENSE) for details.

package/bin/scout-cli.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+/**
+ * AURA Scout CLI
+ *
+ * Interactive command-line tool for testing Scout SDK and Core API.
+ *
+ * Usage:
+ *   npx @aura-labs-ai/scout --api-key YOUR_KEY
+ *   npx @aura-labs-ai/scout --api-key YOUR_KEY --intent "I need 100 widgets"
+ */
+
+import { createScout } from '../src/index.js';
+import { createInterface } from 'readline';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const flags = {};
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith('--')) {
+    const key = args[i].slice(2);
+    const value = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
+    flags[key] = value;
+  }
+}
+
+// Configuration
+const config = {
+  apiKey: flags['api-key'] || process.env.AURA_API_KEY,
+  coreUrl: flags['core-url'] || process.env.AURA_CORE_URL || 'https://aura-labsai-production.up.railway.app',
+};
+
+// SECURITY: Enforce HTTPS for all non-localhost connections
+const coreUrlLower = config.coreUrl.toLowerCase();
+const isLocalhost = coreUrlLower.startsWith('http://localhost') || coreUrlLower.startsWith('http://127.0.0.1');
+if (!coreUrlLower.startsWith('https://') && !isLocalhost) {
+  console.error('Error: Core URL must use HTTPS. Plaintext HTTP is only allowed for localhost development.');
+  console.error(`  Provided: ${config.coreUrl}`);
+  console.error('  Use --core-url https://... or set AURA_CORE_URL with an HTTPS URL.');
+  process.exit(1);
+}
+
+// Help text
+if (flags.help || flags.h) {
+  console.log(`
+AURA Scout CLI - Test buying agent interactions
+
+Usage:
+  scout-cli [options]
+
+Options:
+  --api-key KEY     Your AURA API key (or set AURA_API_KEY env var)
+  --core-url URL    Core API URL (default: production)
+  --intent "TEXT"   Run single intent and exit
+  --max-budget N    Set maximum budget constraint
+  --delivery-by D   Set delivery deadline (ISO date)
+  --help, -h        Show this help
+
+Interactive Mode:
+  Start without --intent for interactive REPL mode.
+
+Examples:
+  scout-cli --api-key sk_test_123 --intent "I need office supplies"
+  scout-cli --api-key sk_test_123 --intent "Buy 500 widgets" --max-budget 50000
+  AURA_API_KEY=sk_test_123 scout-cli
+`);
+  process.exit(0);
+}
+
+// Validate API key
+if (!config.apiKey) {
+  console.error('Error: API key required. Use --api-key or set AURA_API_KEY');
+  process.exit(1);
+}
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+};
+
+function log(color, ...args) {
+  console.log(color, ...args, colors.reset);
+}
+
+function printJSON(obj) {
+  console.log(JSON.stringify(obj, null, 2));
+}
+
+// Initialize Scout
+let scout;
+let currentSession = null;
+
+async function init() {
+  log(colors.cyan, '\n🔍 AURA Scout CLI v0.1.0');
+  log(colors.dim, `   Core: ${config.coreUrl}`);
+
+  scout = createScout(config);
+
+  log(colors.dim, '   Registering with Core...');
+  const { scoutId } = await scout.register();
+  log(colors.green, `   ✓ Registered as ${scoutId}\n`);
+}
+
+// Single intent mode
+async function runSingleIntent(intentText) {
+  const options = {};
+  if (flags['max-budget']) options.maxBudget = parseFloat(flags['max-budget']);
+  if (flags['delivery-by']) options.deliveryBy = new Date(flags['delivery-by']);
+
+  log(colors.blue, `\n📝 Intent: "${intentText}"`);
+  if (options.maxBudget) log(colors.dim, `   Budget: $${options.maxBudget}`);
+  if (options.deliveryBy) log(colors.dim, `   Deliver by: ${options.deliveryBy.toDateString()}`);
+
+  try {
+    const session = await scout.intent(intentText, options);
+    log(colors.green, `\n✓ Session created: ${session.id}`);
+    log(colors.dim, `   Status: ${session.status}`);
+
+    if (session.intent?.parsed) {
+      log(colors.dim, '   Parsed intent:');
+      printJSON(session.intent.parsed);
+    }
+
+    log(colors.yellow, '\n⏳ Waiting for offers...');
+    const offers = await session.waitForOffers({ timeout: 60000 });
+
+    if (offers.length === 0) {
+      log(colors.yellow, '   No offers received');
+    } else {
+      log(colors.green, `\n✓ Received ${offers.length} offer(s):\n`);
+      for (const offer of offers) {
+        log(colors.bright, `   ${offer.beaconName || offer.beaconId}`);
+        log(colors.dim, `   $${offer.totalPrice} | Delivery: ${offer.deliveryDate || 'TBD'}`);
+        log(colors.dim, `   Score: ${offer.score.toFixed(1)} | Meets constraints: ${offer.meetsConstraints}`);
+        if (!offer.meetsConstraints) {
+          log(colors.red, `   Violations: ${offer.constraintViolations.join(', ')}`);
+        }
+        console.log();
+      }
+
+      if (session.bestOffer) {
+        log(colors.green, `   Best offer: ${session.bestOffer.beaconName || session.bestOffer.beaconId}`);
+      }
+    }
+  } catch (error) {
+    log(colors.red, `\n✗ Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Interactive REPL mode
+async function runInteractive() {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: colors.cyan + 'scout> ' + colors.reset,
+  });
+
+  console.log(`
+${colors.bright}Commands:${colors.reset}
+  intent <text>     Create session with purchase intent
+  status            Show current session status
+  offers            List current offers
+  commit <id>       Commit to offer by ID
+  cancel            Cancel current session
+  budget <amount>   Set max budget for next session
+  help              Show this help
+  exit              Exit CLI
+`);
+
+  let constraints = {};
+
+  rl.prompt();
+
+  rl.on('line', async (line) => {
+    const [command, ...rest] = line.trim().split(' ');
+    const arg = rest.join(' ');
+
+    try {
+      switch (command.toLowerCase()) {
+        case 'intent':
+          if (!arg) {
+            log(colors.red, 'Usage: intent <description>');
+            break;
+          }
+          log(colors.blue, `\n📝 Creating session: "${arg}"`);
+          currentSession = await scout.intent(arg, constraints);
+          log(colors.green, `✓ Session: ${currentSession.id}`);
+          log(colors.dim, `  Status: ${currentSession.status}`);
+          break;
+
+        case 'status':
+          if (!currentSession) {
+            log(colors.yellow, 'No active session. Use "intent <text>" first.');
+            break;
+          }
+          await currentSession.refresh();
+          log(colors.cyan, `\nSession: ${currentSession.id}`);
+          log(colors.dim, `Status: ${currentSession.status}`);
+          log(colors.dim, `Active: ${currentSession.isActive}`);
+          break;
+
+        case 'offers':
+          if (!currentSession) {
+            log(colors.yellow, 'No active session.');
+            break;
+          }
+          log(colors.yellow, '⏳ Fetching offers...');
+          const offers = await currentSession.waitForOffers({ timeout: 30000 });
+          if (offers.length === 0) {
+            log(colors.yellow, 'No offers yet.');
+          } else {
+            log(colors.green, `\n${offers.length} offer(s):\n`);
+            for (const offer of offers) {
+              console.log(`  [${offer.id.slice(0, 8)}] ${offer.beaconName || 'Unknown'} - $${offer.totalPrice} (score: ${offer.score.toFixed(1)})`);
+            }
+          }
+          break;
+
+        case 'commit':
+          if (!currentSession) {
+            log(colors.yellow, 'No active session.');
+            break;
+          }
+          if (!arg) {
+            log(colors.red, 'Usage: commit <offer-id>');
+            break;
+          }
+          log(colors.yellow, `⏳ Committing to offer ${arg}...`);
+          const tx = await currentSession.commit(arg);
+          log(colors.green, `✓ Transaction: ${tx.id}`);
+          break;
+
+        case 'cancel':
+          if (!currentSession) {
+            log(colors.yellow, 'No active session.');
+            break;
+          }
+          await currentSession.cancel();
+          log(colors.green, '✓ Session cancelled');
+          currentSession = null;
+          break;
+
+        case 'budget':
+          if (!arg) {
+            log(colors.dim, `Current max budget: ${constraints.maxBudget || 'not set'}`);
+          } else {
+            constraints.maxBudget = parseFloat(arg);
+            log(colors.green, `✓ Max budget set to $${constraints.maxBudget}`);
+          }
+          break;
+
+        case 'delivery':
+          if (!arg) {
+            log(colors.dim, `Delivery deadline: ${constraints.deliveryBy || 'not set'}`);
+          } else {
+            constraints.deliveryBy = new Date(arg);
+            log(colors.green, `✓ Delivery deadline set to ${constraints.deliveryBy.toDateString()}`);
+          }
+          break;
+
+        case 'help':
+          console.log(`
+${colors.bright}Commands:${colors.reset}
+  intent <text>     Create session with purchase intent
+  status            Show current session status
+  offers            List current offers (polls until available)
+  commit <id>       Commit to offer by ID
+  cancel            Cancel current session
+  budget <amount>   Set max budget for next session
+  delivery <date>   Set delivery deadline (e.g., "2026-03-01")
+  help              Show this help
+  exit              Exit CLI
+`);
+          break;
+
+        case 'exit':
+        case 'quit':
+          log(colors.dim, 'Goodbye!');
+          rl.close();
+          process.exit(0);
+          break;
+
+        case '':
+          break;
+
+        default:
+          log(colors.red, `Unknown command: ${command}. Type "help" for commands.`);
+      }
+    } catch (error) {
+      log(colors.red, `Error: ${error.message}`);
+    }
+
+    rl.prompt();
+  });
+
+  rl.on('close', () => {
+    process.exit(0);
+  });
+}
+
+// Main
+async function main() {
+  try {
+    await init();
+
+    if (flags.intent) {
+      await runSingleIntent(flags.intent);
+    } else {
+      await runInteractive();
+    }
+  } catch (error) {
+    log(colors.red, `Fatal error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/examples/basic-purchase.js

@@ -0,0 +1,112 @@
+/**
+ * Basic Purchase Example
+ *
+ * Demonstrates the core Scout SDK flow:
+ * 1. Initialize Scout with API key
+ * 2. Express purchase intent with constraints
+ * 3. Wait for offers
+ * 4. Evaluate and commit to best offer
+ *
+ * Run with: AURA_API_KEY=your-key node examples/basic-purchase.js
+ */
+
+import { createScout } from '../src/index.js';
+
+async function main() {
+  // Initialize Scout
+  const scout = createScout({
+    apiKey: process.env.AURA_API_KEY,
+    // coreUrl: 'http://localhost:3000', // Uncomment for local development
+  });
+
+  console.log('🔍 Scout initialized');
+  console.log(`   Core URL: ${scout.coreUrl}`);
+
+  // Express purchase intent with constraints
+  console.log('\n📝 Creating session with intent...');
+
+  const session = await scout.intent(
+    'I need 500 industrial widgets for manufacturing, grade A quality',
+    {
+      maxBudget: 50000, // $50,000 max
+      deliveryBy: new Date('2026-03-01'), // Need by March 1st
+      hardConstraints: [
+        // Must be grade A
+        { field: 'grade', operator: 'eq', value: 'A' },
+      ],
+      softPreferences: [
+        // Prefer sustainable suppliers (+10 to score)
+        { field: 'sustainable', operator: 'eq', value: true, weight: 10 },
+        // Prefer suppliers with high ratings (+5 per point above 4.0)
+        { field: 'rating', operator: 'gte', value: 4.0, weight: 5 },
+      ],
+    }
+  );
+
+  console.log(`✓ Session created: ${session.id}`);
+  console.log(`  Status: ${session.status}`);
+
+  // Wait for offers from Beacons
+  console.log('\n⏳ Waiting for offers...');
+
+  try {
+    const offers = await session.waitForOffers({
+      timeout: 60000, // Wait up to 60 seconds
+      interval: 2000, // Poll every 2 seconds
+    });
+
+    console.log(`\n✓ Received ${offers.length} offer(s)`);
+
+    // Display all offers
+    for (const offer of offers) {
+      console.log(`\n  📦 ${offer.beaconName || offer.beaconId}`);
+      console.log(`     Product: ${offer.product}`);
+      console.log(`     Price: $${offer.totalPrice.toLocaleString()} (${offer.quantity} × $${offer.unitPrice})`);
+      console.log(`     Delivery: ${offer.deliveryDate || 'TBD'}`);
+      console.log(`     Score: ${offer.score.toFixed(1)}/100`);
+      console.log(`     Meets constraints: ${offer.meetsConstraints ? '✓' : '✗'}`);
+
+      if (!offer.meetsConstraints) {
+        console.log(`     Violations: ${offer.constraintViolations.join(', ')}`);
+      }
+    }
+
+    // Get only offers that meet all constraints
+    const validOffers = session.validOffers;
+    console.log(`\n✓ ${validOffers.length} offer(s) meet all constraints`);
+
+    // Get the best offer (highest score among valid offers)
+    const bestOffer = session.bestOffer;
+
+    if (bestOffer) {
+      console.log(`\n🏆 Best offer: ${bestOffer.beaconName || bestOffer.beaconId}`);
+      console.log(`   Total: $${bestOffer.totalPrice.toLocaleString()}`);
+      console.log(`   Score: ${bestOffer.score.toFixed(1)}/100`);
+
+      // Commit to the best offer
+      console.log('\n💳 Committing to offer...');
+      const transaction = await session.commit(bestOffer.id);
+
+      console.log(`✓ Transaction created: ${transaction.id}`);
+      console.log(`  Status: ${transaction.status}`);
+    } else {
+      console.log('\n⚠️ No offers meet all constraints');
+
+      // Show why offers were rejected
+      for (const offer of offers) {
+        if (!offer.meetsConstraints) {
+          console.log(`   ${offer.beaconName}: ${offer.constraintViolations.join(', ')}`);
+        }
+      }
+    }
+  } catch (error) {
+    if (error.code === 'TIMEOUT') {
+      console.log('\n⚠️ Timed out waiting for offers');
+      console.log('   This may mean no Beacons matched your intent');
+    } else {
+      throw error;
+    }
+  }
+}
+
+main().catch(console.error);