@private.me/xbind 3.0.2 → 3.0.3

package/dist-standalone/cjs/agent-sdk.js

@@ -1,332 +1 @@
-"use strict";
-/**
- * @module agent-sdk
- * Agent builder wrapper for AI-first interface
- *
- * Provides simplified agent creation with ephemeral identities,
- * policy constraints, and automatic lifecycle management.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentBuilder = void 0;
-const shared_1 = require("../_deps/shared/index.js");
-const identity_js_1 = require("./identity.js");
-const agent_call_js_1 = require("./agent-call.js");
-const agent_call_js_2 = require("./agent-call.js");
-const policy_js_1 = require("./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"
- * });
- * ```
- */
-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 (0, identity_js_1.generateIdentity)();
-                if (!idResult.ok) {
-                    return (0, shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.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 (0, identity_js_1.generateIdentity)();
-                if (!idResult.ok) {
-                    return (0, shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.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 (0, shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.AgentErrorCode.INVALID_PARAMS, 'Identity seed must be exactly 32 bytes', { seedLength: options.identity.length }));
-                }
-                const idResult = await (0, identity_js_1.identityFromSeed)(options.identity);
-                if (!idResult.ok) {
-                    return (0, shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.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 (0, shared_1.ok)(agent);
-        }
-        catch (error) {
-            return (0, shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.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 (0, agent_call_js_1.call)(tool, params, callOptions);
-        // Record successful call for rate limiting
-        if (result.ok) {
-            const policyEngine = (0, policy_js_1.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 = (0, policy_js_1.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,
-        };
-    }
-}
-exports.AgentBuilder = AgentBuilder;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.AgentBuilder=void 0;const shared_1=require("../_deps/shared/index.js"),identity_js_1=require("./identity.js"),agent_call_js_1=require("./agent-call.js"),agent_call_js_2=require("./agent-call.js"),policy_js_1=require("./policy.js");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(0,identity_js_1.generateIdentity)();if(!t.ok)return(0,shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.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(0,shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.AgentErrorCode.INVALID_PARAMS,"Identity seed must be exactly 32 bytes",{seedLength:t.identity.length}));const a=await(0,identity_js_1.identityFromSeed)(t.identity);if(!a.ok)return(0,shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.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(0,identity_js_1.generateIdentity)();if(!t.ok)return(0,shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.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},n=new AgentBuilder(e,a,t.policy);return"ephemeral"===i&&a.ttl&&(a.cleanupTimer=setTimeout(()=>{n.cleanup()},a.ttl)),(0,shared_1.ok)(n)}catch(t){return(0,shared_1.err)(new agent_call_js_2.AgentError(agent_call_js_2.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},n=await(0,agent_call_js_1.call)(t,e,a);if(n.ok){const t=(0,policy_js_1.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 n}cleanup(){this._metadata.cleanupTimer&&(clearTimeout(this._metadata.cleanupTimer),this._metadata.cleanupTimer=void 0);(0,policy_js_1.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}}}exports.AgentBuilder=AgentBuilder;