@ophirai/sdk 0.1.0 → 0.2.0

package/dist/buyer.d.ts

@@ -14,6 +14,10 @@ export interface BuyerAgentConfig {
     escrowConfig?: EscrowConfig;
     /** Optional Lockstep verification endpoint for SLA compliance monitoring. */
     lockstepEndpoint?: string;
+    /** Optional registry endpoints for agent discovery. */
+    registryEndpoints?: string[];
+    /** Optional fallback endpoints for A2A discovery when registry is unavailable. */
+    fallbackEndpoints?: string[];
 }
 /**
  * Buy-side negotiation agent. Sends RFQs, collects quotes, ranks them,
@@ -30,6 +34,8 @@ export declare class BuyerAgent {
     private quoteListeners;
     /** Tracks processed message IDs within the replay window to reject duplicate/replayed messages. */
     private seenMessageIds;
+    private registryEndpoints?;
+    private fallbackEndpoints?;
     constructor(config: BuyerAgentConfig);
     /** Check if a message ID has already been processed (replay protection).
      * Records the ID if new; throws DUPLICATE_MESSAGE if already seen.
@@ -49,7 +55,7 @@ export declare class BuyerAgent {
      * const sellers = await buyer.discover({ category: 'llm-inference' });
      * ```
      */
-    discover(_query: {
+    discover(query: {
         category: string;
         requirements?: Record<string, unknown>;
     }): Promise<SellerInfo[]>;

package/dist/buyer.js

@@ -5,6 +5,7 @@ import { NegotiationServer } from './server.js';
 import { NegotiationSession } from './negotiation.js';
 import { JsonRpcClient } from './transport.js';
 import { buildRFQ, buildCounter, buildAccept, buildReject, buildDispute } from './messages.js';
+import { autoDiscover } from './registry.js';
 /**
  * Buy-side negotiation agent. Sends RFQs, collects quotes, ranks them,
  * and accepts/counters/rejects offers. Verifies seller signatures on all
@@ -20,10 +21,14 @@ export class BuyerAgent {
     quoteListeners = new Map();
     /** Tracks processed message IDs within the replay window to reject duplicate/replayed messages. */
     seenMessageIds = new Map();
+    registryEndpoints;
+    fallbackEndpoints;
     constructor(config) {
         this.keypair = config.keypair ?? generateKeyPair();
         this.agentId = publicKeyToDid(this.keypair.publicKey);
         this.endpoint = config.endpoint;
+        this.registryEndpoints = config.registryEndpoints;
+        this.fallbackEndpoints = config.fallbackEndpoints;
         this.transport = new JsonRpcClient();
         this.server = new NegotiationServer();
         this.registerHandlers();
@@ -146,8 +151,16 @@ export class BuyerAgent {
      * const sellers = await buyer.discover({ category: 'llm-inference' });
      * ```
      */
-    async discover(_query) {
-        return [];
+    async discover(query) {
+        const agents = await autoDiscover(query.category, {
+            registries: this.registryEndpoints,
+            fallbackEndpoints: this.fallbackEndpoints,
+        });
+        return agents.map((a) => ({
+            agentId: a.agentId,
+            endpoint: a.endpoint,
+            services: a.services,
+        }));
     }
     /** Send an RFQ to one or more sellers and return the negotiation session.
      * @param params - RFQ parameters including seller targets, service requirements, budget, and SLA

package/dist/index.d.ts

@@ -76,6 +76,20 @@ LockstepBehavioralRequirement,
 LockstepMonitorConfig, 
 /** Result of an SLA compliance check (compliant flag and violation details). */
 ComplianceResult, } from './lockstep.js';
+/** Collect metric observations and evaluate SLA compliance locally. */
+export { MetricCollector } from './metrics.js';
+export type { 
+/** A single metric observation recorded by the buyer. */
+MetricSample, 
+/** A detected SLA violation with evidence. */
+Violation, } from './metrics.js';
+/** Client for the Ophir Agent Registry and autonomous agent discovery. */
+export { OphirRegistry, autoDiscover, BOOTSTRAP_REGISTRIES } from './registry.js';
+export type { 
+/** A registered agent in the Ophir registry. */
+RegisteredAgent, 
+/** Query parameters for finding agents in the registry. */
+RegistryQuery, } from './registry.js';
 /** Convert agreements to x402 HTTP payment headers and parse responses. */
 export { agreementToX402Headers, parseX402Response } from './x402.js';
 /** All protocol-level types re-exported from @ophirai/protocol for convenience. */

package/dist/index.js

@@ -38,6 +38,12 @@ export { discoverAgents, parseAgentCard } from './discovery.js';
 // ── Lockstep verification ───────────────────────────────────────────
 /** Convert agreements to Lockstep specs and monitor SLA compliance. */
 export { agreementToLockstepSpec, LockstepMonitor } from './lockstep.js';
+// ── Metric collection & Lockstep monitoring ────────────────────────
+/** Collect metric observations and evaluate SLA compliance locally. */
+export { MetricCollector } from './metrics.js';
+// ── Agent registry & auto-discovery ────────────────────────────────
+/** Client for the Ophir Agent Registry and autonomous agent discovery. */
+export { OphirRegistry, autoDiscover, BOOTSTRAP_REGISTRIES } from './registry.js';
 // ── x402 payment headers ───────────────────────────────────────────
 /** Convert agreements to x402 HTTP payment headers and parse responses. */
 export { agreementToX402Headers, parseX402Response } from './x402.js';

package/dist/metrics.d.ts

@@ -0,0 +1,55 @@
+import type { LockstepVerificationSpec } from './sla.js';
+/** A single metric observation recorded by the buyer. */
+export interface MetricSample {
+    metric: string;
+    value: number;
+    timestamp: string;
+    agreement_id: string;
+    measurement_window: string;
+    sample_count: number;
+}
+/** A detected SLA violation with evidence. */
+export interface Violation {
+    violation_id: string;
+    agreement_id: string;
+    agreement_hash: string;
+    metric: string;
+    threshold: number;
+    observed: number;
+    operator: string;
+    measurement_window: string;
+    sample_count: number;
+    timestamp: string;
+    consecutive_count: number;
+    samples: MetricSample[];
+    evidence_hash: string;
+}
+/**
+ * Collects metric observations and evaluates behavioral checks from a Lockstep spec.
+ * Runs locally — no external service required.
+ */
+export declare class MetricCollector {
+    private buffers;
+    private agreementId;
+    private agreementHash;
+    private retentionMs;
+    constructor(agreement: {
+        agreement_id: string;
+        agreement_hash: string;
+    }, retentionHours?: number);
+    /** Record a raw observation for a metric. */
+    record(metric: string, value: number): void;
+    /** Evict observations older than the retention window. */
+    private evict;
+    /** Compute the aggregate value for a metric over a measurement window. */
+    aggregate(metric: string, method: string, windowMs: number): {
+        value: number;
+        sampleCount: number;
+    } | null;
+    /** Evaluate all behavioral checks in a Lockstep spec and return violations. */
+    evaluate(spec: LockstepVerificationSpec): Violation[];
+    /** Get the number of observations recorded for a metric. */
+    getObservationCount(metric: string): number;
+    /** Clear all recorded observations. */
+    clear(): void;
+}

package/dist/metrics.js

@@ -0,0 +1,153 @@
+/**
+ * Collects metric observations and evaluates behavioral checks from a Lockstep spec.
+ * Runs locally — no external service required.
+ */
+export class MetricCollector {
+    buffers = new Map();
+    agreementId;
+    agreementHash;
+    retentionMs;
+    constructor(agreement, retentionHours = 168) {
+        this.agreementId = agreement.agreement_id;
+        this.agreementHash = agreement.agreement_hash;
+        this.retentionMs = retentionHours * 3600_000;
+    }
+    /** Record a raw observation for a metric. */
+    record(metric, value) {
+        let buf = this.buffers.get(metric);
+        if (!buf) {
+            buf = { observations: [], consecutiveFailures: 0, lastViolationTime: 0 };
+            this.buffers.set(metric, buf);
+        }
+        buf.observations.push({ value, timestamp: Date.now() });
+        this.evict(buf);
+    }
+    /** Evict observations older than the retention window. */
+    evict(buf) {
+        const cutoff = Date.now() - this.retentionMs;
+        while (buf.observations.length > 0 && buf.observations[0].timestamp < cutoff) {
+            buf.observations.shift();
+        }
+    }
+    /** Compute the aggregate value for a metric over a measurement window. */
+    aggregate(metric, method, windowMs) {
+        const buf = this.buffers.get(metric);
+        if (!buf || buf.observations.length === 0)
+            return null;
+        const cutoff = Date.now() - windowMs;
+        const windowObs = buf.observations.filter((o) => o.timestamp >= cutoff);
+        if (windowObs.length === 0)
+            return null;
+        const values = windowObs.map((o) => o.value);
+        let value;
+        switch (method) {
+            case 'percentile':
+                // For p99, p50 etc — sort and pick percentile
+                values.sort((a, b) => a - b);
+                value = values[Math.floor(values.length * 0.99)] ?? values[values.length - 1];
+                break;
+            case 'count':
+                value = values.length;
+                break;
+            case 'rate':
+                value = values.reduce((s, v) => s + v, 0) / (windowMs / 60_000);
+                break;
+            case 'instant':
+                value = values[values.length - 1];
+                break;
+            case 'rolling_average':
+            default:
+                value = values.reduce((s, v) => s + v, 0) / values.length;
+                break;
+        }
+        return { value, sampleCount: windowObs.length };
+    }
+    /** Evaluate all behavioral checks in a Lockstep spec and return violations. */
+    evaluate(spec) {
+        const violations = [];
+        const now = Date.now();
+        for (const check of spec.behavioral_checks) {
+            const windowMs = parseDuration(check.measurement_window);
+            const agg = this.aggregate(check.metric, check.measurement_method, windowMs);
+            const minSamples = check.min_samples ?? 10;
+            if (!agg || agg.sampleCount < minSamples) {
+                continue;
+            }
+            let failed = false;
+            switch (check.operator) {
+                case 'lte':
+                    failed = agg.value > check.threshold;
+                    break;
+                case 'gte':
+                    failed = agg.value < check.threshold;
+                    break;
+                case 'eq':
+                    failed = agg.value !== check.threshold;
+                    break;
+            }
+            const buf = this.buffers.get(check.metric);
+            if (!buf)
+                continue;
+            if (failed) {
+                buf.consecutiveFailures++;
+            }
+            else {
+                buf.consecutiveFailures = 0;
+                continue;
+            }
+            const policy = check.violation_policy;
+            const requiredFailures = policy?.consecutive_failures ?? 3;
+            const cooldownMs = (policy?.cooldown_seconds ?? 300) * 1000;
+            if (buf.consecutiveFailures < requiredFailures)
+                continue;
+            if (now - buf.lastViolationTime < cooldownMs)
+                continue;
+            buf.lastViolationTime = now;
+            const cutoff = now - windowMs;
+            const windowObs = buf.observations.filter((o) => o.timestamp >= cutoff);
+            const samples = windowObs.map((o) => ({
+                metric: check.metric,
+                value: o.value,
+                timestamp: new Date(o.timestamp).toISOString(),
+                agreement_id: this.agreementId,
+                measurement_window: check.measurement_window,
+                sample_count: 1,
+            }));
+            violations.push({
+                violation_id: crypto.randomUUID(),
+                agreement_id: this.agreementId,
+                agreement_hash: this.agreementHash,
+                metric: check.metric,
+                threshold: check.threshold,
+                observed: agg.value,
+                operator: check.operator,
+                measurement_window: check.measurement_window,
+                sample_count: agg.sampleCount,
+                timestamp: new Date(now).toISOString(),
+                consecutive_count: buf.consecutiveFailures,
+                samples,
+                evidence_hash: '', // Computed by caller via agreementHash(samples)
+            });
+        }
+        return violations;
+    }
+    /** Get the number of observations recorded for a metric. */
+    getObservationCount(metric) {
+        return this.buffers.get(metric)?.observations.length ?? 0;
+    }
+    /** Clear all recorded observations. */
+    clear() {
+        this.buffers.clear();
+    }
+}
+/** Parse an ISO 8601 duration string to milliseconds. Supports PT{n}H, PT{n}M, PT{n}S, P{n}D. */
+function parseDuration(iso) {
+    const match = iso.match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/);
+    if (!match)
+        return 3600_000; // default 1 hour
+    const days = parseInt(match[1] || '0', 10);
+    const hours = parseInt(match[2] || '0', 10);
+    const minutes = parseInt(match[3] || '0', 10);
+    const seconds = parseInt(match[4] || '0', 10);
+    return ((days * 24 + hours) * 3600 + minutes * 60 + seconds) * 1000;
+}

package/dist/registry.d.ts

@@ -0,0 +1,69 @@
+import type { ServiceOffering } from './types.js';
+import type { AgentCard, NegotiationCapability } from './discovery.js';
+/** A registered agent in the Ophir registry. */
+export interface RegisteredAgent {
+    agentId: string;
+    endpoint: string;
+    services: ServiceOffering[];
+    capabilities: NegotiationCapability;
+    registeredAt: string;
+    lastHeartbeat: string;
+    reputation?: {
+        score: number;
+        total_agreements: number;
+        disputes_won: number;
+        disputes_lost: number;
+    };
+}
+/** Query parameters for finding agents in the registry. */
+export interface RegistryQuery {
+    category?: string;
+    maxPrice?: string;
+    currency?: string;
+    minReputation?: number;
+    limit?: number;
+}
+/**
+ * Client for the Ophir Agent Registry — a lightweight discovery service
+ * where agents register their services and buyers find sellers.
+ *
+ * The registry is optional. Agents can also discover each other via
+ * A2A Agent Cards at /.well-known/agent.json, or via direct endpoints.
+ *
+ * Supports multiple registry endpoints for redundancy.
+ */
+export declare class OphirRegistry {
+    private endpoints;
+    private agentId?;
+    private signature?;
+    constructor(endpoints?: string[]);
+    /** Authenticate with the registry using a did:key and signed challenge. */
+    authenticate(agentId: string, signature: string): void;
+    /** Register this agent's services with the registry. */
+    register(card: AgentCard): Promise<{
+        success: boolean;
+        agentId: string;
+    }>;
+    /** Send a heartbeat to keep the registration alive. */
+    heartbeat(agentId: string): Promise<boolean>;
+    /** Find agents matching a query. */
+    find(query: RegistryQuery): Promise<RegisteredAgent[]>;
+    /** Unregister this agent from the registry. */
+    unregister(agentId: string): Promise<boolean>;
+}
+/**
+ * Well-known bootstrap endpoints for Ophir agent discovery.
+ * These can be embedded in agent frameworks so that any agent
+ * with the Ophir SDK can automatically find and negotiate with
+ * service providers without prior configuration.
+ */
+export declare const BOOTSTRAP_REGISTRIES: readonly ["https://registry.ophir.ai/v1"];
+/**
+ * Auto-discover Ophir sellers for a service category.
+ * Tries the registry first, falls back to A2A discovery via known endpoints.
+ */
+export declare function autoDiscover(category: string, options?: {
+    registries?: string[];
+    fallbackEndpoints?: string[];
+    maxResults?: number;
+}): Promise<RegisteredAgent[]>;

package/dist/registry.js

@@ -0,0 +1,166 @@
+/**
+ * Client for the Ophir Agent Registry — a lightweight discovery service
+ * where agents register their services and buyers find sellers.
+ *
+ * The registry is optional. Agents can also discover each other via
+ * A2A Agent Cards at /.well-known/agent.json, or via direct endpoints.
+ *
+ * Supports multiple registry endpoints for redundancy.
+ */
+export class OphirRegistry {
+    endpoints;
+    agentId;
+    signature;
+    constructor(endpoints) {
+        this.endpoints = endpoints ?? ['https://registry.ophir.ai/v1'];
+    }
+    /** Authenticate with the registry using a did:key and signed challenge. */
+    authenticate(agentId, signature) {
+        this.agentId = agentId;
+        this.signature = signature;
+    }
+    /** Register this agent's services with the registry. */
+    async register(card) {
+        for (const endpoint of this.endpoints) {
+            try {
+                const res = await fetch(`${endpoint}/agents`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...(this.agentId ? { 'X-Agent-Id': this.agentId } : {}),
+                        ...(this.signature ? { 'X-Agent-Signature': this.signature } : {}),
+                    },
+                    body: JSON.stringify(card),
+                });
+                if (res.ok) {
+                    const data = await res.json();
+                    return { success: true, agentId: data.agent_id };
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return { success: false, agentId: '' };
+    }
+    /** Send a heartbeat to keep the registration alive. */
+    async heartbeat(agentId) {
+        for (const endpoint of this.endpoints) {
+            try {
+                const res = await fetch(`${endpoint}/agents/${encodeURIComponent(agentId)}/heartbeat`, {
+                    method: 'POST',
+                    headers: {
+                        ...(this.agentId ? { 'X-Agent-Id': this.agentId } : {}),
+                    },
+                });
+                if (res.ok)
+                    return true;
+            }
+            catch {
+                continue;
+            }
+        }
+        return false;
+    }
+    /** Find agents matching a query. */
+    async find(query) {
+        const params = new URLSearchParams();
+        if (query.category)
+            params.set('category', query.category);
+        if (query.maxPrice)
+            params.set('max_price', query.maxPrice);
+        if (query.currency)
+            params.set('currency', query.currency);
+        if (query.minReputation !== undefined)
+            params.set('min_reputation', String(query.minReputation));
+        if (query.limit !== undefined)
+            params.set('limit', String(query.limit));
+        for (const endpoint of this.endpoints) {
+            try {
+                const res = await fetch(`${endpoint}/agents?${params.toString()}`);
+                if (res.ok) {
+                    const data = await res.json();
+                    return data.agents;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return [];
+    }
+    /** Unregister this agent from the registry. */
+    async unregister(agentId) {
+        for (const endpoint of this.endpoints) {
+            try {
+                const res = await fetch(`${endpoint}/agents/${encodeURIComponent(agentId)}`, {
+                    method: 'DELETE',
+                    headers: {
+                        ...(this.agentId ? { 'X-Agent-Id': this.agentId } : {}),
+                        ...(this.signature ? { 'X-Agent-Signature': this.signature } : {}),
+                    },
+                });
+                if (res.ok)
+                    return true;
+            }
+            catch {
+                continue;
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Well-known bootstrap endpoints for Ophir agent discovery.
+ * These can be embedded in agent frameworks so that any agent
+ * with the Ophir SDK can automatically find and negotiate with
+ * service providers without prior configuration.
+ */
+export const BOOTSTRAP_REGISTRIES = [
+    'https://registry.ophir.ai/v1',
+];
+/**
+ * Auto-discover Ophir sellers for a service category.
+ * Tries the registry first, falls back to A2A discovery via known endpoints.
+ */
+export async function autoDiscover(category, options) {
+    const registry = new OphirRegistry(options?.registries);
+    const results = await registry.find({
+        category,
+        limit: options?.maxResults ?? 10,
+    });
+    if (results.length > 0)
+        return results;
+    // Fallback: A2A discovery via known endpoints
+    if (options?.fallbackEndpoints) {
+        const { discoverAgents, parseAgentCard } = await import('./discovery.js');
+        const cards = await discoverAgents(options.fallbackEndpoints);
+        return cards
+            .map((card) => {
+            const neg = card.capabilities?.negotiation;
+            if (!neg?.supported)
+                return null;
+            const services = (neg.services ?? [])
+                .filter((s) => !category || s.category === category)
+                .map((s) => ({
+                category: s.category,
+                description: s.description,
+                base_price: s.base_price,
+                currency: s.currency,
+                unit: s.unit,
+            }));
+            if (services.length === 0)
+                return null;
+            return {
+                agentId: card.url,
+                endpoint: neg.endpoint,
+                services,
+                capabilities: neg,
+                registeredAt: new Date().toISOString(),
+                lastHeartbeat: new Date().toISOString(),
+            };
+        })
+            .filter((a) => a !== null);
+    }
+    return [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ophirai/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK for the Ophir Agent Negotiation Protocol — BuyerAgent, SellerAgent, Ed25519 signing, Solana escrow, and SLA enforcement",
   "type": "module",
   "main": "dist/index.js",