@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/agent-sdk.js

@@ -1 +1,328 @@
-import{ok,err}from"./_deps/shared/index.js";import{generateIdentity,identityFromSeed}from"./identity.js";import{call}from"./agent-call.js";import{AgentError,AgentErrorCode}from"./agent-call.js";import{getGlobalPolicyEngine}from"./policy.js";export class AgentBuilder{_identity;_metadata;_policy;constructor(t,e,i){this._identity=t,this._metadata=e,this._policy=i}get did(){return this._identity.did}get name(){return this._metadata.name}get created(){return this._metadata.created}get identityMode(){return this._metadata.identityMode}get ttl(){return this._metadata.ttl}get timeRemaining(){if(!this._metadata.ttl)return;const t=Date.now()-this._metadata.created,e=this._metadata.ttl-t;return e>0?e:0}static async create(t){try{let e,i;if(t.identity&&"ephemeral"!==t.identity)if("persistent"===t.identity){const t=await generateIdentity();if(!t.ok)return err(new AgentError(AgentErrorCode.AUTHENTICATION_FAILED,"Failed to generate persistent identity",{cause:t.error}));e=t.value,i="persistent"}else if(t.identity instanceof Uint8Array){if(32!==t.identity.length)return err(new AgentError(AgentErrorCode.INVALID_PARAMS,"Identity seed must be exactly 32 bytes",{seedLength:t.identity.length}));const a=await identityFromSeed(t.identity);if(!a.ok)return err(new AgentError(AgentErrorCode.AUTHENTICATION_FAILED,"Failed to derive identity from seed",{cause:a.error}));e=a.value,i="persistent"}else e=t.identity,i="persistent";else{const t=await generateIdentity();if(!t.ok)return err(new AgentError(AgentErrorCode.AUTHENTICATION_FAILED,"Failed to generate ephemeral identity",{cause:t.error}));e=t.value,i="ephemeral"}const a={name:t.name,did:e.did,created:Date.now(),identityMode:i,ttl:"ephemeral"===i?t.ttl??36e5:void 0},r=new AgentBuilder(e,a,t.policy);return"ephemeral"===i&&a.ttl&&(a.cleanupTimer=setTimeout(()=>{r.cleanup()},a.ttl)),ok(r)}catch(t){return err(new AgentError(AgentErrorCode.AUTHENTICATION_FAILED,t instanceof Error?t.message:"Unknown error during agent creation",{originalError:t}))}}async call(t,e,i){const a={...i,policy:this._policy?{...this._policy,...i?.policy,allowedTools:i?.policy?.allowedTools?[...this._policy.allowedTools||[],...i.policy.allowedTools]:this._policy.allowedTools,scopes:i?.policy?.scopes?[...this._policy.scopes||[],...i.policy.scopes]:this._policy.scopes,limits:{amountPerTxn:Math.min(this._policy.limits?.amountPerTxn??1/0,i?.policy?.limits?.amountPerTxn??1/0)===1/0?void 0:Math.min(this._policy.limits?.amountPerTxn??1/0,i?.policy?.limits?.amountPerTxn??1/0),dailyAmount:Math.min(this._policy.limits?.dailyAmount??1/0,i?.policy?.limits?.dailyAmount??1/0)===1/0?void 0:Math.min(this._policy.limits?.dailyAmount??1/0,i?.policy?.limits?.dailyAmount??1/0),callsPerMinute:Math.min(this._policy.limits?.callsPerMinute??1/0,i?.policy?.limits?.callsPerMinute??1/0)===1/0?void 0:Math.min(this._policy.limits?.callsPerMinute??1/0,i?.policy?.limits?.callsPerMinute??1/0)}}:i?.policy},r=await call(t,e,a);if(r.ok){const t=getGlobalPolicyEngine();if(t.recordCall(this.did),"object"==typeof e&&null!==e){const i=e,a=i.amount??i.value??i.price??i.total;"number"==typeof a&&t.recordSpending(this.did,a)}}return r}cleanup(){this._metadata.cleanupTimer&&(clearTimeout(this._metadata.cleanupTimer),this._metadata.cleanupTimer=void 0);getGlobalPolicyEngine().reset(this.did)}extendTTL(t){if("ephemeral"!==this._metadata.identityMode||!this._metadata.ttl)return!1;this._metadata.cleanupTimer&&clearTimeout(this._metadata.cleanupTimer);const e=Date.now()-this._metadata.created,i=this._metadata.ttl-e+t;return this._metadata.ttl=this._metadata.ttl+t,this._metadata.cleanupTimer=setTimeout(()=>{this.cleanup()},i),!0}toJSON(){return{name:this.name,did:this.did,created:this.created,identityMode:this.identityMode,ttl:this.ttl,timeRemaining:this.timeRemaining}}}
+/**
+ * @module agent-sdk
+ * Agent builder wrapper for AI-first interface
+ *
+ * Provides simplified agent creation with ephemeral identities,
+ * policy constraints, and automatic lifecycle management.
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { generateIdentity, identityFromSeed } from './identity.js';
+import { call } from './agent-call.js';
+import { AgentError, AgentErrorCode } from './agent-call.js';
+import { getGlobalPolicyEngine } from './policy.js';
+/**
+ * Agent builder - AI-first wrapper for xBind agent creation
+ *
+ * Provides high-level API for creating agents with automatic
+ * identity management, policy enforcement, and lifecycle cleanup.
+ *
+ * This is the simplified xBind agent builder for AI agents. For full
+ * transport-level control, use the Agent class from './agent.js'.
+ *
+ * @example
+ * ```typescript
+ * // Create ephemeral agent (auto-cleanup after 1 hour)
+ * const agent = await AgentBuilder.create({
+ *   name: "invoice-agent",
+ *   policy: {
+ *     allowedTools: ["payments:createCharge", "payments:refund"],
+ *     limits: {
+ *       amountPerTxn: 1000,
+ *       dailyAmount: 10000
+ *     }
+ *   }
+ * });
+ *
+ * // Use agent to call tools
+ * const result = await agent.call("payments:createCharge", {
+ *   amount: 100,
+ *   currency: "USD"
+ * });
+ * ```
+ */
+export class AgentBuilder {
+    /** Agent identity (cryptographic keys + DID) */
+    _identity;
+    /** Agent metadata */
+    _metadata;
+    /** Policy constraints (optional) */
+    _policy;
+    /**
+     * Create a new AgentBuilder instance.
+     *
+     * @param identity - Agent identity
+     * @param metadata - Agent metadata
+     * @param policy - Optional policy constraints
+     */
+    constructor(identity, metadata, policy) {
+        this._identity = identity;
+        this._metadata = metadata;
+        this._policy = policy;
+    }
+    /**
+     * Agent DID (decentralized identifier).
+     */
+    get did() {
+        return this._identity.did;
+    }
+    /**
+     * Agent name.
+     */
+    get name() {
+        return this._metadata.name;
+    }
+    /**
+     * Creation timestamp (milliseconds since epoch).
+     */
+    get created() {
+        return this._metadata.created;
+    }
+    /**
+     * Identity mode ('ephemeral' or 'persistent').
+     */
+    get identityMode() {
+        return this._metadata.identityMode;
+    }
+    /**
+     * Time-to-live for ephemeral agents (milliseconds).
+     * Returns undefined for persistent agents.
+     */
+    get ttl() {
+        return this._metadata.ttl;
+    }
+    /**
+     * Time remaining until auto-cleanup (milliseconds).
+     * Returns undefined for persistent agents or if already expired.
+     */
+    get timeRemaining() {
+        if (!this._metadata.ttl)
+            return undefined;
+        const elapsed = Date.now() - this._metadata.created;
+        const remaining = this._metadata.ttl - elapsed;
+        return remaining > 0 ? remaining : 0;
+    }
+    /**
+     * Create a new agent instance.
+     *
+     * @param options - Agent creation options
+     * @returns AgentBuilder instance or error
+     *
+     * @example
+     * ```typescript
+     * // Ephemeral agent (default)
+     * const agent = await AgentBuilder.create({
+     *   name: "task-agent",
+     *   policy: {
+     *     allowedTools: ["slack:sendMessage"],
+     *     limits: { callsPerMinute: 10 }
+     *   }
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Persistent agent from seed
+     * const seed = new Uint8Array(32);
+     * crypto.getRandomValues(seed);
+     *
+     * const agent = await AgentBuilder.create({
+     *   name: "persistent-agent",
+     *   identity: seed, // Deterministic DID
+     * });
+     * ```
+     */
+    static async create(options) {
+        try {
+            // Determine identity mode
+            let identity;
+            let identityMode;
+            if (!options.identity || options.identity === 'ephemeral') {
+                // Generate ephemeral identity
+                const idResult = await generateIdentity();
+                if (!idResult.ok) {
+                    return err(new AgentError(AgentErrorCode.AUTHENTICATION_FAILED, 'Failed to generate ephemeral identity', { cause: idResult.error }));
+                }
+                identity = idResult.value;
+                identityMode = 'ephemeral';
+            }
+            else if (options.identity === 'persistent') {
+                // Generate persistent identity
+                const idResult = await generateIdentity();
+                if (!idResult.ok) {
+                    return err(new AgentError(AgentErrorCode.AUTHENTICATION_FAILED, 'Failed to generate persistent identity', { cause: idResult.error }));
+                }
+                identity = idResult.value;
+                identityMode = 'persistent';
+            }
+            else if (options.identity instanceof Uint8Array) {
+                // Deterministic identity from seed
+                if (options.identity.length !== 32) {
+                    return err(new AgentError(AgentErrorCode.INVALID_PARAMS, 'Identity seed must be exactly 32 bytes', { seedLength: options.identity.length }));
+                }
+                const idResult = await identityFromSeed(options.identity);
+                if (!idResult.ok) {
+                    return err(new AgentError(AgentErrorCode.AUTHENTICATION_FAILED, 'Failed to derive identity from seed', { cause: idResult.error }));
+                }
+                identity = idResult.value;
+                identityMode = 'persistent';
+            }
+            else {
+                // Use provided AgentIdentity
+                identity = options.identity;
+                identityMode = 'persistent';
+            }
+            // Create metadata
+            const metadata = {
+                name: options.name,
+                did: identity.did,
+                created: Date.now(),
+                identityMode,
+                ttl: identityMode === 'ephemeral' ? (options.ttl ?? 3600000) : undefined,
+            };
+            // Create agent instance
+            const agent = new AgentBuilder(identity, metadata, options.policy);
+            // Setup auto-cleanup for ephemeral agents
+            if (identityMode === 'ephemeral' && metadata.ttl) {
+                metadata.cleanupTimer = setTimeout(() => {
+                    agent.cleanup();
+                }, metadata.ttl);
+            }
+            return ok(agent);
+        }
+        catch (error) {
+            return err(new AgentError(AgentErrorCode.AUTHENTICATION_FAILED, error instanceof Error ? error.message : 'Unknown error during agent creation', { originalError: error }));
+        }
+    }
+    /**
+     * Call a tool/service via xBind.
+     *
+     * This method wraps agent-call.ts call() function with agent context
+     * and enforces policy constraints defined during agent creation.
+     *
+     * @param tool - Tool alias (e.g., "stripe:createCharge")
+     * @param params - Parameters to pass to the tool
+     * @param options - Optional call options (overrides agent policy)
+     * @returns Result with response data and audit receipt, or error
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.call("payments:createCharge", {
+     *   amount: 100,
+     *   currency: "USD"
+     * });
+     *
+     * if (!result.ok) {
+     *   console.error(`Payment failed: ${result.error.message}`);
+     *   return;
+     * }
+     *
+     * console.log(`Charge created: ${result.value.data.id}`);
+     * console.log(`Audit: ${result.value.audit.timestamp}`);
+     * ```
+     */
+    async call(tool, params, options) {
+        // Merge agent policy with call-specific options
+        const callOptions = {
+            ...options,
+            policy: this._policy ? {
+                ...this._policy,
+                ...options?.policy,
+                // Merge allowed tools arrays
+                allowedTools: options?.policy?.allowedTools
+                    ? [...(this._policy.allowedTools || []), ...options.policy.allowedTools]
+                    : this._policy.allowedTools,
+                // Merge scopes arrays
+                scopes: options?.policy?.scopes
+                    ? [...(this._policy.scopes || []), ...options.policy.scopes]
+                    : this._policy.scopes,
+                // Take minimum of limits (most restrictive)
+                limits: {
+                    amountPerTxn: Math.min(this._policy.limits?.amountPerTxn ?? Infinity, options?.policy?.limits?.amountPerTxn ?? Infinity) === Infinity ? undefined : Math.min(this._policy.limits?.amountPerTxn ?? Infinity, options?.policy?.limits?.amountPerTxn ?? Infinity),
+                    dailyAmount: Math.min(this._policy.limits?.dailyAmount ?? Infinity, options?.policy?.limits?.dailyAmount ?? Infinity) === Infinity ? undefined : Math.min(this._policy.limits?.dailyAmount ?? Infinity, options?.policy?.limits?.dailyAmount ?? Infinity),
+                    callsPerMinute: Math.min(this._policy.limits?.callsPerMinute ?? Infinity, options?.policy?.limits?.callsPerMinute ?? Infinity) === Infinity ? undefined : Math.min(this._policy.limits?.callsPerMinute ?? Infinity, options?.policy?.limits?.callsPerMinute ?? Infinity),
+                },
+            } : options?.policy,
+        };
+        // Delegate to agent-call.ts call() function
+        const result = await call(tool, params, callOptions);
+        // Record successful call for rate limiting
+        if (result.ok) {
+            const policyEngine = getGlobalPolicyEngine();
+            policyEngine.recordCall(this.did);
+            // Record spending if amount is in params
+            if (typeof params === 'object' && params !== null) {
+                const obj = params;
+                const amount = obj.amount ?? obj.value ?? obj.price ?? obj.total;
+                if (typeof amount === 'number') {
+                    policyEngine.recordSpending(this.did, amount);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Cleanup agent resources.
+     *
+     * For ephemeral agents, this clears the cleanup timer and marks
+     * the agent as cleaned up. For persistent agents, this is a no-op.
+     *
+     * This method is called automatically when TTL expires for ephemeral agents.
+     */
+    cleanup() {
+        if (this._metadata.cleanupTimer) {
+            clearTimeout(this._metadata.cleanupTimer);
+            this._metadata.cleanupTimer = undefined;
+        }
+        // Reset policy engine state for this agent
+        const policyEngine = getGlobalPolicyEngine();
+        policyEngine.reset(this.did);
+    }
+    /**
+     * Extend TTL for ephemeral agents.
+     *
+     * @param additionalTime - Additional time in milliseconds
+     * @returns true if extended, false if not an ephemeral agent
+     *
+     * @example
+     * ```typescript
+     * // Extend by 30 minutes
+     * agent.extendTTL(30 * 60 * 1000);
+     * ```
+     */
+    extendTTL(additionalTime) {
+        if (this._metadata.identityMode !== 'ephemeral' || !this._metadata.ttl) {
+            return false;
+        }
+        // Clear existing timer
+        if (this._metadata.cleanupTimer) {
+            clearTimeout(this._metadata.cleanupTimer);
+        }
+        // Calculate new TTL (extend the total TTL, not just remaining time)
+        const elapsed = Date.now() - this._metadata.created;
+        const currentRemaining = this._metadata.ttl - elapsed;
+        const newRemaining = currentRemaining + additionalTime;
+        // Update the TTL to reflect the extension
+        // SAFETY: We're modifying metadata which is intentionally mutable for lifecycle management
+        this._metadata.ttl = this._metadata.ttl + additionalTime;
+        // Setup new timer
+        this._metadata.cleanupTimer = setTimeout(() => {
+            this.cleanup();
+        }, newRemaining);
+        return true;
+    }
+    /**
+     * Convert agent to JSON-serializable format.
+     *
+     * @returns Agent metadata (without private keys)
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            did: this.did,
+            created: this.created,
+            identityMode: this.identityMode,
+            ttl: this.ttl,
+            timeRemaining: this.timeRemaining,
+        };
+    }
+}