@aura-labs-ai/scout 0.2.0

package/src/intent-session.js

@@ -0,0 +1,233 @@
+/**
+ * IntentSession — Conversational Intent Completeness Checker
+ *
+ * Accumulates natural language text across multiple submit() calls,
+ * checks completeness via @aura-labs-ai/nlp, and generates clarification
+ * questions for missing categories.
+ *
+ * Used by Scout SDK's createIntentSession() to validate intent
+ * completeness locally before sending to Core.
+ *
+ * State machine:
+ *   idle → checking → incomplete → checking → ... → complete
+ *
+ * Design:
+ *   - Presence detection only (not semantic authority — that's Core's job)
+ *   - Works with or without an LLM provider (regex-only fallback)
+ *   - Produces a completeness attestation for Core (informational, not authoritative)
+ *   - Max 2 clarification questions per round (per @aura-labs-ai/nlp design)
+ *
+ * Ref: ADR-002, DEC-024, DEC-025, NEUTRAL_BROKER.md Property 1
+ */
+
+import { checkCompleteness } from '@aura-labs-ai/nlp';
+import { generateClarification } from '@aura-labs-ai/nlp';
+
+// ── IntentSession ────────────────────────────────────────────
+
+/**
+ * @typedef {Object} SubmitResult
+ * @property {boolean}   complete   — Whether the intent is complete enough
+ * @property {string[]}  missing    — Category names still unresolved
+ * @property {string}    question   — Clarification question (empty when complete)
+ * @property {number}    confidence — 0-1 overall confidence
+ */
+
+/**
+ * Conversational intent session for accumulating and validating
+ * intent completeness before submission to Core.
+ */
+class IntentSession {
+  #texts = [];
+  #state = 'idle'; // idle | checking | incomplete | complete
+  #rounds = [];
+  #lastResult = null;
+  #provider;
+  #activityLogger;
+  #providerTimeoutMs;
+
+  /**
+   * @param {Object} [options]
+   * @param {Object} [options.provider] — LLM provider for model-based detection
+   * @param {Object} [options.activityLogger] — Activity logger for events
+   * @param {number} [options.providerTimeoutMs=10000] — Timeout for provider calls in ms
+   */
+  constructor(options = {}) {
+    this.#provider = options.provider || null;
+    this.#activityLogger = options.activityLogger || null;
+    this.#providerTimeoutMs = options.providerTimeoutMs || 10_000;
+
+    this.#emitEvent('intent_session.created', {});
+  }
+
+  /**
+   * Submit text to the session. Accumulates with previous text
+   * and checks completeness.
+   *
+   * @param {string} text — Additional intent text from the user
+   * @returns {Promise<SubmitResult>}
+   */
+  async submit(text) {
+    // If already complete, return cached result
+    if (this.#state === 'complete' && this.#lastResult) {
+      return this.#lastResult;
+    }
+
+    // Accumulate text
+    const trimmed = (text || '').trim();
+    if (trimmed.length > 0) {
+      this.#texts.push(trimmed);
+    }
+
+    // Build the full accumulated text
+    const fullText = this.getText();
+
+    this.#state = 'checking';
+    this.#emitEvent('intent_session.submitted', { text: trimmed, roundNumber: this.#rounds.length + 1 });
+
+    try {
+      // Check completeness via @aura-labs-ai/nlp with timeout protection.
+      // Provider calls (remote LLM) can hang — enforce a ceiling.
+      const completenessPromise = checkCompleteness(fullText, {
+        provider: this.#provider,
+      });
+      const completenessResult = await Promise.race([
+        completenessPromise,
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('Provider timeout')), this.#providerTimeoutMs),
+        ),
+      ]);
+
+      // Generate clarification question for missing categories
+      const clarification = generateClarification(
+        completenessResult.missing,
+        { previousRounds: this.#rounds },
+      );
+
+      // Record this round
+      this.#rounds.push({
+        categories_addressed: this.#getAddressedCategories(completenessResult),
+        userResponse: trimmed,
+      });
+
+      // Build result
+      const result = {
+        complete: completenessResult.complete,
+        missing: completenessResult.missing,
+        question: clarification.question || '',
+        confidence: completenessResult.confidence,
+      };
+
+      // Update state
+      this.#state = completenessResult.complete ? 'complete' : 'incomplete';
+      this.#lastResult = result;
+
+      this.#emitEvent(
+        completenessResult.complete ? 'intent_session.complete' : 'intent_session.incomplete',
+        {
+          complete: completenessResult.complete,
+          missing: completenessResult.missing,
+          confidence: completenessResult.confidence,
+          roundNumber: this.#rounds.length,
+        },
+      );
+
+      return result;
+    } catch (error) {
+      // Graceful degradation — return incomplete with error info
+      this.#state = 'incomplete';
+      const result = {
+        complete: false,
+        missing: ['unknown'],
+        question: 'Could you provide more details about your requirements?',
+        confidence: 0,
+      };
+      this.#lastResult = result;
+      return result;
+    }
+  }
+
+  /**
+   * Get the completeness attestation for Core.
+   * Returns null if the session is not yet complete.
+   *
+   * This attestation is informational only — Core retains exclusive
+   * semantic authority per NEUTRAL_BROKER.md Property 1.
+   *
+   * @returns {Object|null}
+   */
+  getAttestation() {
+    if (this.#state !== 'complete' || !this.#lastResult) {
+      return null;
+    }
+
+    return {
+      complete: true,
+      missing: this.#lastResult.missing,
+      confidence: this.#lastResult.confidence,
+      rounds: this.#rounds.length,
+    };
+  }
+
+  /**
+   * Get the full accumulated text.
+   * @returns {string}
+   */
+  getText() {
+    return this.#texts.join(' ');
+  }
+
+  /**
+   * Get the current state.
+   * @returns {'idle'|'checking'|'incomplete'|'complete'}
+   */
+  get state() {
+    return this.#state;
+  }
+
+  /**
+   * Get the number of rounds completed.
+   * @returns {number}
+   */
+  get roundCount() {
+    return this.#rounds.length;
+  }
+
+  /**
+   * Reset the session to idle state.
+   */
+  reset() {
+    this.#texts = [];
+    this.#state = 'idle';
+    this.#rounds = [];
+    this.#lastResult = null;
+    this.#emitEvent('intent_session.reset', {});
+  }
+
+  // ── Private ──────────────────────────────────────────────────
+
+  /**
+   * Determine which categories were addressed in this round
+   * by looking at what's now present.
+   */
+  #getAddressedCategories(completenessResult) {
+    const addressed = [];
+    for (const [name, cat] of Object.entries(completenessResult.categories)) {
+      if (cat.present) {
+        addressed.push(name);
+      }
+    }
+    return addressed;
+  }
+
+  /**
+   * Emit an activity event if logger is available.
+   */
+  #emitEvent(type, data) {
+    if (this.#activityLogger && typeof this.#activityLogger.record === 'function') {
+      this.#activityLogger.record(type, data);
+    }
+  }
+}
+
+export { IntentSession };

package/src/key-manager.js

@@ -0,0 +1,204 @@
+/**
+ * Agent Key Manager — Ed25519 Identity Management
+ *
+ * Manages the agent's root Ed25519 key pair, which is the foundation
+ * of its cryptographic identity in the AURA network.
+ *
+ * Key responsibilities:
+ *   - Generate or load the root key pair
+ *   - Sign data (registration proofs, request signatures)
+ *   - Build canonical signing strings for HTTP request authentication
+ *   - Provide pluggable storage adapters for persistence across restarts
+ *
+ * Key format: raw 32-byte Ed25519 keys, base64-encoded (compatible with
+ * tweetnacl.js in browser contexts and Node.js crypto module).
+ */
+
+import crypto from 'node:crypto';
+import { MemoryStorage } from '@aura-labs-ai/sdk-common';
+
+// Re-export for backward compatibility
+export { MemoryStorage };
+
+// Ed25519 DER prefixes for raw key <-> KeyObject conversion
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');   // public key
+const PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex'); // private key
+
+/**
+ * KeyManager — Manages an agent's Ed25519 root key pair
+ *
+ * @param {object} options
+ * @param {object} [options.storage] - Storage adapter with get/set/remove methods
+ * @param {string} [options.storagePrefix] - Key prefix for storage (default: 'aura:agent:')
+ */
+export class KeyManager {
+  #storage;
+  #prefix;
+  #publicKeyBase64 = null;
+  #privateKeyObject = null;
+  #publicKeyObject = null;
+  #initialized = false;
+
+  constructor({ storage, storagePrefix } = {}) {
+    this.#storage = storage || new MemoryStorage();
+    this.#prefix = storagePrefix || 'aura:agent:';
+  }
+
+  /**
+   * Initialize the key manager — load existing keys or generate new ones
+   *
+   * @returns {Promise<{ publicKey: string, isNew: boolean }>}
+   *   publicKey is base64-encoded raw 32-byte Ed25519 public key
+   *   isNew is true if a new key pair was generated
+   */
+  async init() {
+    if (this.#initialized) {
+      return { publicKey: this.#publicKeyBase64, isNew: false };
+    }
+
+    // Try to load existing keys from storage
+    const storedPublic = await this.#storage.get(`${this.#prefix}publicKey`);
+    const storedPrivate = await this.#storage.get(`${this.#prefix}privateKey`);
+
+    if (storedPublic && storedPrivate) {
+      this.#publicKeyBase64 = storedPublic;
+      this.#publicKeyObject = this.#rawPublicToKeyObject(storedPublic);
+      this.#privateKeyObject = this.#rawPrivateToKeyObject(storedPrivate);
+      this.#initialized = true;
+      return { publicKey: this.#publicKeyBase64, isNew: false };
+    }
+
+    // Generate new key pair
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+
+    // Extract raw bytes for storage and interop
+    const spkiDer = publicKey.export({ type: 'spki', format: 'der' });
+    const rawPublic = spkiDer.subarray(spkiDer.length - 32);
+    this.#publicKeyBase64 = rawPublic.toString('base64');
+
+    const pkcs8Der = privateKey.export({ type: 'pkcs8', format: 'der' });
+    const rawPrivate = pkcs8Der.subarray(pkcs8Der.length - 32);
+    const rawPrivateBase64 = rawPrivate.toString('base64');
+
+    // Store for persistence
+    await this.#storage.set(`${this.#prefix}publicKey`, this.#publicKeyBase64);
+    await this.#storage.set(`${this.#prefix}privateKey`, rawPrivateBase64);
+
+    this.#publicKeyObject = publicKey;
+    this.#privateKeyObject = privateKey;
+    this.#initialized = true;
+
+    return { publicKey: this.#publicKeyBase64, isNew: true };
+  }
+
+  /**
+   * Sign arbitrary data with the agent's private key
+   *
+   * @param {string} data - String data to sign
+   * @returns {string} Base64-encoded Ed25519 signature (64 bytes)
+   * @throws {Error} If not initialized
+   */
+  sign(data) {
+    this.#ensureInitialized();
+    const signature = crypto.sign(null, Buffer.from(data), this.#privateKeyObject);
+    return signature.toString('base64');
+  }
+
+  /**
+   * Build and sign the canonical request string for HTTP request authentication
+   *
+   * Format: "${method}\n${path}\n${timestamp}\n${bodyDigest}"
+   *
+   * @param {object} params
+   * @param {string} params.method - HTTP method (uppercase)
+   * @param {string} params.path - Request path (e.g., /sessions)
+   * @param {string|null} params.body - JSON body string or null
+   * @returns {{ signature: string, timestamp: string }} Signature and timestamp to include in headers
+   */
+  signRequest({ method, path, body }) {
+    this.#ensureInitialized();
+
+    const timestamp = Date.now().toString();
+    const bodyDigest = body
+      ? crypto.createHash('sha256').update(body).digest('base64')
+      : '';
+    const signingString = `${method}\n${path}\n${timestamp}\n${bodyDigest}`;
+    const signature = this.sign(signingString);
+
+    return { signature, timestamp };
+  }
+
+  /**
+   * Get the public key (base64-encoded raw 32-byte Ed25519)
+   *
+   * @returns {string|null} Public key or null if not initialized
+   */
+  get publicKey() {
+    return this.#publicKeyBase64;
+  }
+
+  /**
+   * Check if the key manager has been initialized
+   *
+   * @returns {boolean}
+   */
+  get isInitialized() {
+    return this.#initialized;
+  }
+
+  /**
+   * Compute the key fingerprint (SHA-256 hex of raw public key)
+   *
+   * @returns {string} 64-char hex fingerprint
+   */
+  get fingerprint() {
+    this.#ensureInitialized();
+    return crypto.createHash('sha256')
+      .update(Buffer.from(this.#publicKeyBase64, 'base64'))
+      .digest('hex');
+  }
+
+  /**
+   * Load the stored agentId from storage
+   *
+   * @returns {Promise<string|null>}
+   */
+  async getAgentId() {
+    return this.#storage.get(`${this.#prefix}agentId`);
+  }
+
+  /**
+   * Store the agentId after registration
+   *
+   * @param {string} agentId - UUID from /agents/register response
+   */
+  async setAgentId(agentId) {
+    await this.#storage.set(`${this.#prefix}agentId`, agentId);
+  }
+
+  // ─── Private helpers ────────────────────────────────────────────────
+
+  #ensureInitialized() {
+    if (!this.#initialized) {
+      throw new Error('KeyManager not initialized. Call init() first.');
+    }
+  }
+
+  /**
+   * Convert raw 32-byte base64 public key to Node.js KeyObject
+   */
+  #rawPublicToKeyObject(base64Key) {
+    const rawBytes = Buffer.from(base64Key, 'base64');
+    const derKey = Buffer.concat([SPKI_PREFIX, rawBytes]);
+    return crypto.createPublicKey({ key: derKey, format: 'der', type: 'spki' });
+  }
+
+  /**
+   * Convert raw 32-byte base64 private key (seed) to Node.js KeyObject
+   */
+  #rawPrivateToKeyObject(base64Key) {
+    const rawBytes = Buffer.from(base64Key, 'base64');
+    const derKey = Buffer.concat([PKCS8_PREFIX, rawBytes]);
+    return crypto.createPrivateKey({ key: derKey, format: 'der', type: 'pkcs8' });
+  }
+}